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Introduction 



■ Mye\come to BEA WebLogic Server 8 For Dummies. Whether you are an 
▼ ▼ administrator, a developer, a manager, or all of the above, you will find 
something in this book to make your job easier. 

WebLogic is the most widely used application server on the market today. 
You can use WebLogic in large or small projects and to develop both tradi- 
tional client-server as well as web-based applications. 



About This Book 

This book gives you a broad understanding of BEA WebLogic Server. 
The main audience consists of developers and administrators, but anyone 
involved in a WebLogic project will benefit from reading this book. Managers 
can gain an overview of the components that make up their system. Quality 
assurance personnel can benefit from the same understanding. 

For developers, this book shows quick examples to get you up and running 
in many of the technologies supported by WebLogic. Rather than give you 
extensive application examples, I focus on short, easy-to-follow examples 
than can become the starting point for something more complex. For admin- 
istrators, I step you through many common WebLogic tasks and the configu- 
ration settings you should use. 

Finally, everyone should have an understanding of how the components of a 
web application fit together and what WebLogic can do for your application. 
This book gives you that viewpoint too. 



Contentions Used in This Book 

Throughout this book, several typefaces are used. Here's a brief explanation: 

When an important term is introduced, it appears in italics. 
All URLs in the book appear in computer font. For example: 

www . bea . com 
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V The code examples appear in computer font as well. For instance: 

int i=0; 



when a variable or command appears in the text, it's in computer 
font too. For example: "The JAVA_0PTI0NS variable allows you to pass 
additional parameters to the Java virtual machine." 

Directories appear in computer font. You'll see something like this: 
"You should switch to the webl ogi c\bi n directory." 

Sometimes, you'll see 7 ta 7 7 c computer font, such as 
c : \webl ogi c\bi n> install -name yourhlebLogi cServer 

This means you should type everything as written, except you should 
replace yourWebLogicServer with — you guessed it — the name of your 
server. 

t<" When you should choose menu options, each option is separated by an 
arrow, like this: StartOAll ProgramsOAccessoriesOCommand Prompt. 

v 0 Code listings contain complete Java source files or configuration files. A 
code listing always has a title, such as "Listing 1-1: Count to Ten." 

W Code snippets are small sections of source code that do not make up a 
complete source file on their own. 



What \lou Don't Hatfe to Read 

For Dummies books are designed so that you can read any chapter you like, in 
any order you want. This makes it easier to skip chapters that contain informa- 
tion you're already familiar with or simply don't need. In addition, if you 

I Already have a WebLogic server up and running, you can skip Part I. 

V Are familiar with EJB development or aren't planning to use EJBs, you 
can skip Part II. 

Are not using web services, you can skip Part III. 

Are developing a non-web application, you can skip Part IV. 

f" Are just starting out with WebLogic, don't concern yourself too much 
with clustering, security, and performance tuning. These Part V topics 
might be useful later, though. 

V Just want to get started with WebLogic, Part VI (which contains many 
suggestions for using WebLogic) is not essential reading. 
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Id have at least a passing knowledge of the Java programming lan- 
guage, but you don't need to be an expert in Java. You should be familiar with 
the following concepts: 

■ )S Entering Java programs 

Compiling and executing Java programs 
W Using classes, methods, and variables 

You should also have a basic familiarity with the Internet, including the use of 
web browsers and downloading software from web sites. 

You should also have some knowledge of SQL to understand how WebLogic 
accesses external data, which is stored in databases. It is not necessary for 
you to be an SQL expert, but you should be familiar with basic SELECT, 
INSERT, UPDATE, and DELETE statements. 



How This Book Is Organized 

BEA WebLogic Server 8 For Dummies has six parts. As you proceed through 
the book, each part increases in complexity. Each chapter covers a specific 
topic and provides code examples, explanations, and sample projects for you 
to complete. As you complete each chapter, you will have completed one or 
more projects that demonstrate the main ideas discussed in that chapter. 



Part 1: Installing and Configuring 
WebLogic 

I begin by showing you how to install WebLogic. If you need no special 
options, installing WebLogic can be as easy as installing any other Windows 
application. If your installation has special needs, it can be a bit trickier. I 
show you a standard installation and describe the details of a more complex 
installation. After you find out how to install WebLogic, you discover how to 
customize it to meet your needs. 
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Creating web applications is perhaps the most common use for WebLogic. In 
Part II, you find out about some of the components that make up a web appli- 
cation. One of the primary components is Enterprise JavaBeans (EJB). I show 
you how to construct various types of EJBs and describe their differences. 



Part 111: Employing Web Services 

Web services work much like any Java object that contains a set of reusable 
methods. The main difference is that a web service allows other programs to 
call these methods through the Internet. Web services are usually accessed 
using the simple object access protocol (SOAP), which means different sys- 
tems can communicate. An object hosted on a Windows computer could be 
accessed by a Macintosh, for example. In this part, you create a web service 
using WebLogic. You also find out how to access your own web services and 
those provided by third parties. 



Part IV: The Forgotten Services 

A number of services run behind the scenes, so they're not noticed in a typical 
web application. These services take care of binding the entire application 
together and providing access to the underlying databases. For example, 
Java Database Connectivity (JDBC) allows your web application to access 
databases, Java Message Service (JMS) allows programs to exchange mes- 
sages, and Java Naming and Directory Interface (JNDI) allows named resources 
to be located. In Part IV, you discover the ins and outs of all these "behind the 
scenes" services. 



Part V: Big-lime, Heaty-buty 
Server Configuration 

After you develop your application and test it, you're ready for the big time. 
Part V shows you some of the more advanced configuration options available 
in WebLogic. For example, clustering allows you to use many different server 
computers as one large virtual server. A virtual server can be much more reli- 
able and can process information faster than a single server. You also find out 
about different security issues and how to resolve them. 
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Part VI: The Part of Tens 




you find out about ten best practices that are a result of my experi- 
hte^^tffi WebLogic and web development in general. I also provide tips for 
administrators and general tips to heed before going live. 



Icons Used in This Book 

This icon signals a tip that I think you might find useful. These tips are pro- 
vided to jumpstart your knowledge of WebLogic and save you from having to 
go through a lot of trial and error. 




This icon lets you know that the information you're about to read is some- 
thing that's often overlooked but should be remembered. For example, when 
you're setting a configuration option, doing so may have an unintended side 
effect. The remember icon will alert you to this. 



Technical stuff is important, and you may find it interesting. But understand- 
ing something flagged with this icon is not necessary to accomplishing a job. 



This icon means what it says. Pay attention to the common pitfalls or errors 
described. These warnings are issues that I have run into myself. By heeding 
these warnings, you can save yourself the time that I spent learning these 
issues. 




Where to Go from Here 

This book will give you a solid introduction to WebLogic. This will definitely 
get you up and running with a web application. However, entire books are dedi- 
cated to many of the topics that are covered here in a single chapter. In particu- 
lar, you may want to check out books on some of these topics: EJB, JSP, JSTL, 
JMS, JDBC, and Java. You can find a lot of information about WebLogic on the 
web. Visit the WebLogic documentation site at http : //e-docs . bea . com and 
the Sun site at http : //Java .sun . com. 
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In this part . . . 

\J ou begin by finding out exactly what an application 

server is. You look at the major components of an 
application server and how WebLogic implements them. 

Installation is the first step in setting up your WebLogic- 
based application. You find out how to install WebLogic 
on a single machine. Then you look at installing 
WebLogic on many machines using a script. You also 
discover a variety of ways to start WebLogic Server. 

Configuration is an important and ongoing part of setting 
up WebLogic Server. You need to configure WebLogic to 
initially set up your web application. Later, you need to 
monitor and adapt your server's configuration to the 
changing needs of your users. All these topics are covered 
in this part. 
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In This Chapter 

Understanding the role of application servers 
Meeting the J2EE family of technologies 
Outlining the major features of WebLogic 




/n the most general sense, a server is a program that provides information 
to a client that requests that information. Sometimes a server is a computer 
used to centralize resources so that they can be shared by a number of differ- 
ent users. For instance, file servers centralize file storage, database servers 
centralize data storage, and web servers centralize the distribution of web con- 
tent. In a similar vein, an application server centralizes key programming tasks. 
Doing so has many advantages, as you will discover. 

In this chapter, you find out about application servers, in particular BEA's 
WebLogic Server. In a recent Gartner study, BEA WebLogic Server had 34 per- 
cent of the application server market share — the largest market share of any 
single vendor. BEA Systems is at the forefront of market developments and 
support of new standards. 

WebLogic is not the only application server on the market. WebLogic's 
main competitors are IBM's WebSphere and JBoss, an open-source applica- 
tion server released under the LGPL license. In addition to these two Java- 
based application servers, WebLogic faces non-Java competition, mainly from 
the growing Microsoft .NET family of products. 



Enterprise JavaBeans (EJB) is a technology for developing, assembling, 
deploying, and managing distributed applications in an enterprise environ- 
ment. This basically means that EJB provides a Java framework for executing 
objects residing on different machines over a distributed network. This is a 
powerful capability: It enables a user to harness the power of different 
machines transparently, in a single application. 
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A machine hosting and executing an EJB object is called an EJB application 
server. WebLogic, as an EJB application server, also acts as a container for 

pntainer provides a management system for EJB objects. An efficient 
removes the need for users and developers (to a certain extent) to 
be concerned about exactly how an object will be used. Put another way, an 
EJB application server provides APIs and interfaces, and an EJB is like a plug- 
in that provides business logic for a specific application. As a developer, you're 
writing modules (EJBs) that are dropped into the application server, which 
then loads and runs the EJBs when needed. 



Servers work closely with clients. A client requests information from a server 
or requests that a server do something. The server, acting on the request, 
sends the requested information to the client or does what it is asked to do. 

BEA WebLogic Server, as an EJB application server, interacts with clients in a 
similar manner. The machine that requests WebLogic to run an EJB program 
is the client. This client program can be a stand-alone Java program or another 
server. (Often web servers are the clients for the services of EJBs.) EJBs allow 
a busy web server to focus on what it was designed to do: serve web pages. 
The web server calls upon EJBs, which reside on an application server, to 
perform business-specific tasks, such as retrieving data from a database. 

This division of labor is the key reason to use an application server. Dividing 
the task between the client and the application server results in three imme- 
diate advantages: 

Reliability 
v 0 Scalability 
v* Modularity 



Achieving reliability through redundancy 

You can run an application on your desktop machine only as long as your 
machine is operational. In other words, if your machine "hangs" (becomes 
locked) or the power goes off, you can't continue to work. Application servers, 
on the other hand, can offer a more reliable way of running an application 
through a concept called redundancy. This simply means that you add multi- 
ple servers, instruct them to act together as if they were a single server, and 
then allow clients to access them. If one of the servers becomes unavailable, 
the other servers pick up the slack and respond to the needs of the clients. 

You can also work on an ailing server without disturbing the other servers. 
You are free to reboot the crashed application server without affecting the 
stability of the remaining application servers. Using multiple application 
servers in this way can increase the reliability of your application. 
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Making applications scalable 



[and more clients make requests of an application server, more and 
ands are placed on that server. As the overall demands become 
greater, the capability of the server to quickly fulfill each individual request 
decreases. One solution to this problem is to add more horsepower to the 
machine used to run the application server — perhaps more memory, a 
faster hard drive, or even a faster CPU. A better solution, however, is to add 
another server, clustering it with the existing server. Now the deluge of client 
requests can be serviced by two machines acting as one. Need more power? 
Add a third, fourth, or fifth machine. This is the essence of scalability. 

As requests for services come in from the clients, the cluster automatically 
dispatches these requests to the least busy of the application servers. This 
allows you to increase the capacity of your application by simply adding 
additional application servers rather than going through the costly process 
of upgrading a production server. As a bonus, the additional servers also 
increase the reliability of your system. 



Improving modularity 

Modularity has long been one of the chief design goals of computer program- 
ming. Modular program design breaks the program into smaller units, or mod- 
ules, that are developed separately. Often these modules can be reused across 
several applications. Object oriented programming (OOP) was created to facil- 
itate the creation of modular programs, among other design goals. 

One of the most fundamental ways of making a program modular is to 
separate presentation logic — the part of the program that interacts with the 
user — from business logic — the part of the program that makes decisions 
and performs calculations. Presentation logic should be housed in the web 
server, because the web server is responsible for transmitting the HTML that 
will be presented to the user. Business logic should be housed in the applica- 
tion server so that it can be reused by any web pages that may need it. The 
same business logic is often needed across many web pages. For example, 
the business logic to update inventory would be reused on any page that 
affects inventory. 

An application server enables this separation. Business logic is placed in 
EJBs. The application server executes the EJBs, and the results are sent to 
the presentation program running on the web server. 
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Java 2 Platform, Enterprise Edition (J2EE) contains additions to the Java envi- 
ronment that Sun Microsystems created to facilitate such enterprise con- 
cepts as application servers. Sun has defined a specific way in which to build 
application servers for Java. One advantage to this approach is that content 
you develop for WebLogic Server can be used also with other J2EE applica- 
tion servers. In other words, you can migrate the content to another J2EE 
application server, if needed. 

J2EE is not just one technology, but rather a collection of technologies. Sun 
defines standards embodied as J2EE, which other vendors implement. For 
example, WebLogic implements the following J2EE components: 

v 0 JavaServer Pages (JSP) 
f" Enterprise JavaBeans (EJB) 

Java Transaction Service (JTS) 
u* Java Message Service (JMS) 
V Java Naming and Directory Interface (JNDi) 

In other chapters, you find out more about these components of J2EE. In this 
section, I briefly review the function of each of these to give you an overview 
of how they fit together. 



JavaServer Pages (JSP) allow you to embed Java code directly into HTML-like 
documents. JSP has access to nearly all the core features of the Java pro- 
gramming language, except you're returning only streams back to the user's 
browser. This allows you to construct complex applications using only JSP. 
However, just because you can construct complex JSP-based applications 
does not mean that you should. JSP is best restricted to presentation logic, 
with more complex business logic delegated to EJBs. 



Enterprise JavaBeans (EJB) technology allows code to be executed on a 
remote system. This remote system is the application server. EJB is com- 
monly used to isolate business logic from presentation logic, which usually 
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Enterprise JaVaBeans 
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consists of JSP. EJB coordinates access with the database and shields higher 
levels, such as JSP, from the need to directly access the database. In this way, 
re to change database servers or the format of your database, all 
ted to data access would be in one location. 



JaVa Transaction Service 

Java Transaction Service (JTS) is a transaction manager that allows requests 
to be segmented into transactions. These transactions succeed or fail as a 
whole. This prevents partial transactions from persisting if only a part of the 
transaction is successful. 



JaVa Message Service 

The Java Message Service (JMS) API was developed to allow Java applications 
to be message driven. A message-compatible EJB can receive and generate 
messages. These messages can contain any data needed by the program. 
Messaging is asynchronous, so considerable time can elapse before a response 
message is received, if at all. JMS also allows messages to be saved to a mes- 
sage store, such as a file or a database. 



JaVa Naming and Directory Interface 

Java Naming and Directory Interface (JNDI) is a standard extension to the Java 
platform that provides naming and directory information to Java programs. 
This allows EJB and other resources to have names that can be looked up by 
their client programs. JNDI is a high-level standard and can use any number 
of underlying name and directory services. 



Enterprise applications 

Enterprise applications tie many of the previously mentioned components 
together into one application. An enterprise application is most commonly 
made up of a web application and any EJB that may be used by that web appli- 
cation. The entire enterprise application is packaged as a single archive file, 
which can be easily deployed to a server such as WebLogic. This allows for 
easy packaging, distribution, and deployment of your enterprise applications. 
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ned, WebLogic is the most popular application server available for 
Java. WebLogic has gained this popularity due, in part, to a full set of fea- 
tures. In this section, you are introduced to some of these features. In other 
chapters, they are described in much greater detail. 

Throughout this text, I refer to BEA's WebLogic Server product simply as 
WebLogic. BEA, however, uses the term WebLogic to refer to a family of prod- 
ucts, including WebLogic Portal, WebLogic Integration, WebLogic Workshop, 
and WebLogic Express. The popularity of the core WebLogic Server product, 
however, has led to the shortening of the name to simply WebLogic in many 
circles. 



Platform support 

WebLogic can run on many platforms, including Windows and many flavors of 
UNIX. WebLogic is available also for many large mainframe computer systems, 
providing WebLogic with greater processing power and scalability. The exten- 
sive platform support of WebLogic allows you to mix and match technologies. 
For example, you might run WebLogic on a mainframe computer system, back- 
ing it up with a cluster of less expensive machines that run the same applica- 
tions. Further, you can test your application on less expensive machines and 
run your production system on more expensive, higher-bandwidth hardware. 



Web applications 

Although WebLogic is most commonly thought of as an application server, it 
can also handle many web server functions. This means WebLogic could be 
used as an all-in-one solution. JavaServer Pages (JSP) is one of the most 
common forms of server-side Java programming. WebLogic includes the 
capability to execute JSP. You can to create web applications in WebLogic 
that make use of technologies such as JSP and custom tag libraries. Web 
applications are covered in Chapter 5. 



EJB support 

Perhaps the most basic feature of a Java-based application server is support 
for Enterprise JavaBeans (EJB). WebLogic includes extensive support for the 
five types of EJB: 
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I Stateless bean 
■-^ tr* Stateful bean 

UrOpDOOkS-gebean 

1 V Container-managed persistence (CMP) entity bean 
v 0 Bean-managed persistence (BMP) entity bean 

Additionally, WebLogic makes other important services available to these 
beans, such as database connection pooling and naming services. EJB sup- 
port is discussed in Chapters 6 and 7. 



Database connectivity 

Databases are often the heart of any serious application. Because of this, 
WebLogic includes extensive support for relational databases. One of the most 
important features is database connection pooling. This allows WebLogic — 
instead of individual EJBs — to manage connections to the database. 

Database connections are an expensive resource. Processor cycles and 
extensive network communication are required to open and close these 
connections, and this can slow down other operations. By using a database 
connection pool, WebLogic can reuse its pool of open database connections, 
freeing the application from the overhead of constantly creating and destroy- 
ing database connections. Database connectivity is discussed more fully in 
Chapter 12. 



Web services 

Web services are a new technology that provides a more uniform way of 
accessing the components of an application. Web services allow your appli- 
cation to receive XML messages from other applications and respond to 
those requests using XML. This means other applications can make use of 
your application using only the HTTP protocol. 

XML messages are sent and received using the Simple Object Access Protocol 
(SOAP), a W3C standard that specifies how web services should be accessed 
by their client programs. By supporting a standard protocol such as SOAP, 
many different systems can access the web services that you make available 
through WebLogic Server. Web services are discussed in Chapter 9. Acces- 
sing web services is discussed in Chapter 10. 
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One of the new features of WebLogic (as of Version 7) is WebLogic Workshop, 
which enables someone who is not familiar with J2EE to construct web ser- 
bLogic Workshop provides a number of tools and frameworks to 
igning web services easier. WebLogic Workshop is discussed in 
Chapter 11. 



Clustering 

Clustering is the capability to chain together many individual application 
servers. These application servers are clones of each other, performing the 
same task. The clustering capabilities of WebLogic enable these servers to 
handle requests even though some of the application servers may fail. This 
greatly increases the reliability of your application. 

Clustering also allows your web application to become very scalable. 
Because you now have many application servers handling requests from 
clients, you can handle a greater number of incoming requests. Clustering is 
discussed in more detail in Chapter 16. 



Security 

Security is a major concern in any application — and when your application 
is accessible through the Internet, the need for security increases. WebLogic 
can help you with three specific areas of security: 

V Securing your data transmissions. Data transmissions are secured using 
SSL/HTTPS. This prevents a hacker from accessing data packets as they 
are transmitted between the browser and the web server. 

f Controlling access by users. You may want to restrict some users from 
accessing the overall system and restrict other users from accessing 
only certain parts of the system. WebLogic provides features that allow 
you to define users and control exactly what they have access to. 

Verifying administrators. WebLogic's Administration Console enables 
you to easily configure your server remotely. Unfortunately, this also 
means that a hacker can configure your system remotely. WebLogic pro- 
vides security to all configuration programs to limit access by unautho- 
rized users. Security is discussed in Chapter 18. 
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In This Chapter 

Preparing to install 
Installing using GUI mode 
Introducing Configuration Wizard 
Installing using console mode 
Installing using silent mode 
••••••••••••••••••••••••••••••••••••••••••••••••a 

■ t makes sense that before you can use WebLogic, you must install it on 
«( the machine that you want to use as your Internet server. This chapter 
discusses the different ways that you can install the program on your system. 
Even if you inherited a server that already has WebLogic installed, you will 
probably want to at least skim this chapter so that you're aware of the differ- 
ent installation (and configuration) options available. 



Installation OverView 

Installing WebLogic is a straightforward process. WebLogic has several instal- 
lation methods available, one of which should fit your needs: 

GUI installation. This is the most common method of installing 
WebLogic — and the easiest. The graphical user interface (GUI) allows 
you to see what's happening during the installation process. 

V Console installation. If you're working with a so-called "headless" 
remote server, which allows only terminal connections, this installation 
method is for you. 

V Silent installation. If you need to install WebLogic on a number of differ- 
ent systems, you can "script" the installation process to make it quicker 
and easier. 
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All three installation methods work on both Windows and UNIX systems. 
Which installation method should you choose? Unless restricted by the capa- 
the target system, the answer lies in your needs and your comfort 
your computer. Each installation method is covered in this chapter, 
so you can get a good idea of which method you should choose. 



First, however, you should know the system requirements for WebLogic as 
well as how to get your hands on the software. It also doesn't hurt to know 
how WebLogic is licensed by BEA Systems. Read on for all the details! 



System requirements 

Before you can take a class at a local college, you must meet the prerequi- 
sites. To be successful in the class, you must fulfill the stated requirements. 
The same is true of WebLogic Server. The installation program will check that 
your system has met certain prerequisites before it attempts the installation. 
Those requirements are outlined in this section. 

Essentially, you need a computer system that will function well under Windows 
NT Server 4; Windows 2000 Server; Windows 2000 Advanced Server; Sun 
Solaris 7, 8, or 9; HP-UX 1 1 or 1 li; IBM AIX 4.3.3 or 5L; or several flavors of 
Linux. If your system will run one of these comfortably, you should have no 
problems running WebLogic. 

You can find detailed information about which systems are certified to work 
with WebLogic at the following address: 

http://e-docs.bea. com/ 



Hard-driVe space requirements 

If you install the complete WebLogic Server, approximately 525MB of disk 
space are required. This number includes 35MB for the JDK installation and 
142MB for the examples. This is only the hard-drive space required for 
WebLogic itself. Your own application data will require additional space. 

Hard-drive space requirements used to be considerably more important 
when hard drives cost more money than they do these days. It takes a con- 
siderable amount of trouble to move a system from one hard drive to a larger 
drive. Due to the low cost of hard drives today, it simply makes sense to go 
for one of the larger sizes available for your system. 




It's likely that continuous operation of WebLogic Server will be important. 
Because of this, you should apply the same measures to WebLogic Server 
as you do to any other production server. For example, you may use a RAID 
array to provide redundant hard drives. This way, if one of your hard drives 
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fails, your system will continue running while you replace the faulty hard 
drive. Plus, with a RAID array, your system does not go down during the 
ent. The full scope of your system's redundancy and reliability 
is, in the end, driven by uptime needs and budget. 




Memory requirements 

Just as regular applications have memory requirements, so does WebLogic. 
However, the memory requirements for WebLogic are considerably higher 
than regular end-user applications that you may have installed. For WebLogic 
Server, 1GB of RAM is recommended. You can get by with less RAM, but it 
may degrade the performance of your server. 

JDK requirements 

WebLogic requires Java to be present. If you're using a Windows installation, 
a copy of Java Development Kit is bundled with your installation program. 

Some UNIX distributions of WebLogic do not include a copy of JDK. Versions 
of the WebLogic installation program that do include JDK have a .bin exten- 
sion. If you're trying to install from one of these distributions, you must make 
sure that the JDK BIN directory is in your path. If you don't have a copy of 
JDK already installed on your system, you should use a version of WebLogic 
that includes JDK. 

Finding out whether Java is properly installed on your UNIX or Windows 
machine is easy. Simply enter the following command at the command 
prompt: 

Java -version 

If Java is properly installed, you'll see the version information for your JDK. If 
Java isn't installed, you'll get an error. For more information about installing Java, 
refer to the online documentation provided with JDK that you downloaded. 

Other requirements 

Finally, if you're installing using the GUI installation program, you must have a 
color depth of at least 8 bits. Nearly any computer produced since 1997 will 
have a color depth of at least 8 bits and most likely higher. If you're using either 
of the other two installation methods, you don't need to worry about color. 



Getting WebLogic 

WebLogic is available on CD-ROM or from the BEA Systems web site. If you 
have WebLogic on CD-ROM, you save some time because you don't have to 
download a huge installation file. (CD-ROMs are available for purchase from 
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any BEA Systems sales representative.) Most people download WebLogic 
from the BEA Systems web site. You can find the download here: 

/commerce .beasys.com/showallversions.jsp?family=WLS 

eding URL is accurate as of this writing, but it may have changed by 
you read this book. 

Registration is required of everyone who wants to download. After register- 
ing, you can proceed to the download area. 

You can download WebLogic in two ways. The first is called the net installer 
and is similar to many net-aware installation programs. You essentially down- 
load a 20MB installation program and answer some questions; then the instal- 
lation program downloads additional elements, as necessary. 

The second download method is called the package installer. With this 
method, you download the entire stand-alone installation program, which 
varies in size depending on the version of WebLogic you want to download. 
(The size could be anywhere from 155MB to 275MB.) This option is great if 
you want to keep a copy of the installation program on CD (as a backup). If 
you plan on doing a silent installation, you must download the entire package 
installer. The silent installation mode is not supported by the net installer. 

If you choose to use the net installer, the installation process is similar to 
downloading the package installer and using the GUI installation. Refer to the 
appropriate major sections, later in this chapter, for more information on 
each of the installation modes and how to use them. 




Understanding licensing 

To use WebLogic Server, you must have a valid license. When you first install 
WebLogic, an evaluation license is created and is valid for 90 days. This evalua- 
tion version works just like a real license, except that you're limited to 20 con- 
current connections. After this evaluation period is up, you must purchase a 
real WebLogic license. 

You can choose from two different licenses: 

Development license 
v 0 Production license 

A development license, which costs less than the production license, allows 
only 15 concurrent connections at a time. A production license has no con- 
nection limit. 
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The development license allows you to create several development servers, 
potentially one for each of your developers, to create your system before you 
tl§S£ jKnto production. This spares you the prohibitive cost of buying a pro- 
)icense for each developer. 

If you have licenses for older versions of WebLogic, you must purchase new 
license files. Contact BEA software to see whether upgrade pricing is available. 



Usinq the GUI Mode Installer 

The easiest way to install WebLogic is to use the GUI mode installer. This pro- 
gram uses a graphical user interface to guide you through the installation 
process. Here's how to do an installation using the GUI mode installer: 

1. If you obtained WebLogic as a CD-ROM product, insert the CD-ROM in 
your CD-ROM drive. If you obtained WebLogic from the web, double- 
click the installer that you downloaded. 

The installer program begins, and you see the Welcome screen shown in 
Figure 2-1. 



Figure 2-1: 

The 
Welcome 
screen 
for the 
WebLogic 
GUI 

installation. 



ii .• BEA Installer - WebLogic Platform 8.1 



Welcome 

This installs! will guide you through the installation oF 
WebLogic Platform 8.1, 



Cbea 



Click the Next button to proceed to the next screen , If you want to 
change entries in a previous screen, click the Previous button, You rr 
quit the installer at any time by clicking the Exit button. 



2. Click Next. 

A license agreement appears. 

3. Assuming you agree to all the fine print, choose the Yes option and 
click Next. 
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The screen shown in Figure 2-2 appears. The BEA home directory is 
where the common programs used by all BEA software are stored. The 
ult home directory on Windows is c:\bea. 



Figure 2-2: 

Specify a 
BEA home 
directory. 



» . BEA Installer -WebLogic Platform 8.1 



Choose BEA Home Directory 

Specify the BEA Home where you wish to install 
WebLogic Platform 8,1, 



BEA Home Type 



® Create a 



BEA Home Directory 



4. Use the default directory or choose a new directory. 

If you want a new directory, click Browse and select the directory or 
type a new directory path in the text box just above the Browse button. 

5. When you're satisfied with the home directory, click Next. 

The screen shown in Figure 2-3 appears. 



Figure 2-3: 

Choose 
the type of 
installation. 



b . BEA Installer - WebLogic Plat form 8.1 
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Choose Install Type 

Select the type of installation you wish to perforn 
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® Typical Installation 

(2) 

O Custom Installation 



Choose software components to install and optionally create 
custom application domains. Recommended For advanced users. 
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6. Choose the type of installation you want and then click Next. 

Usually, you'll want to perform a typical installation. If you choose 

ical Installation, skip to Step 8. You might choose Custom Installation 
u don't want certain WebLogic components installed for security or 
space considerations. 

7. If you choose Custom Installation, specify what you want to install, as 
shown in Figure 2-4, and then click Next. 

By default, all components are installed. If you don't need a certain com- 
ponent installed, clear the check box beside its name. 



Figure 2-4: 

You can 
specify 
which 
components 
to install. 



, BEA Installer - WebLogic Platform 8.1 

Choose Components 

Select the components of WebLogic Platform 8.1 you wish to install. 
Greyed components are already installed. 



0 □ WebLogic Server 
0 Server 

0 Server Examples 
0 C] WebLogic Workshop 

0 Workshop Runtime Framework 

0 WebLogic Workshop Application Developer Edition 

0 Workshop Samples 



Description 



8. Specify a directory for WebLogic, as shown in Figure 2-5. 

In Steps 4 and 5, you created a BEA home directory. This step creates a 
directory for WebLogic itself. This product directory is usually a sub- 
directory of the BEA home directory. The product directory will contain 
all files needed by your application. 

As in Steps 3 and 4, you can use the default directory, you can use the 
Browse button to select a different directory, or you can simply type a 
new directory path in the text box. 

9. When you're satisfied with the product directory, click Next. 

The installation begins. In the installer's title bar and in the lower-right 
corner, you can see progress indicators. When the indicators reach 
100%, the installation is complete, and you see a Congratulations mes- 
sage, as shown in Figure 2-6. 
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Figure 2-5: 

Choose a 
directory for 
installing 
WebLogic. 



» . BEA Installer - WebLogic Platform 8.1 



Choose Product Directory 

pftvide the directory where you wish to install 



BEA Home Directory 

C:\baa 



Product Installation Directory 



C:i,be.3'iweblogic81 



Note the option shown at the bottom of Figure 2-6. This option allows you to 
install XML Spy, which is an XML development environment. 



Figure 2-6: 

Congrat- 
ulations. 

You've 
installed 
WebLogic. 



k. BEA In staller - WebLogic Platform 8.1 
Installation Complete 

Click the Done button to e*it the installer. 



Cbea 



Congratulations! WebLogic Platfbrn 
lo C:^bea\ w «blogic81. 



t.l has been successfully installed 



0 Install XML Spy 



Using Configuration Wizard 



In this section, you use Configuration Wizard to create a server. After 
installing WebLogic, Configuration Wizard is accessible right away. 
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Throughout this process, you'll see references to a domain. Although a 
domain can contain multiple web servers, the examples in this chapter 
that your domain has only one server. For more on domains, see 
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To create a domain, follow these steps. 

1. Choose StartOBEA WebLogic Platform 8.10Configuration Wizard. 

Configuration Wizard starts and the screen shown in Figure 2-7 appears. 

2. Select the Create a new WebLogic configuration option, and then Click 
Next. 

In this example, you create a server. To modify an existing server, you 
would choose the Add to an existing WebLogic configuration option. 

3. Select a template and type a name for your domain. Click Next. 

To follow along with the example, select the Basic WebLogic Server 
Domain template. 

4. Choose Express as your configuration type. 

This is the most common option. (You might choose Customized if you 
want to create a clustered environment, which is covered in Chapter 16.) 



Figure 2-7: 
BEA 
Configur- 
ation 
Wizard. 



l] BEA WebLoijic Configuration Wizard 



Create a Configuration or Add to an Existing Configuration 

The Configuration Wi;ard will guide you through the necessary steps to generate 
a new WebLogic configuration, or to add to an existing WebLogic configuration, 



® Create a new WebLogic configuration 

Start here to create a WebLogic configuration in your projects directory, 

Use this option to replicate a configuration from on one of the templates included with WebLogic 
Platform 8,1, or from on one of your own, 

O Add to an existing WebLogic configuration 

Start here to extend an existing WebLogic configuration, 

Use this option to add applications and services, including Database access (JDBC) and Messaging QMS), 
This option also provides the ability to extend functionality by enabling WebLogic Workshop and other 
Platform components. 
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5. Create the administrative user. 

To create the administrative user, type a user name and a password. 
<^lly, the password should be something that's not found in the diction- 
i>^and should consist of both letters and numbers. 

Make sure that you remember the user name and password because 
you'll need them to change configuration settings on your server. 

6. Click Next. 

The screen shown in Figure 2-8 appears. 

7. Review your settings, and then click Create. 

In a few moments, your domain is created. 



Figure 2-8: 

Server 
summary. 



>] BEA WebLogic Configuration Wizard 



■Q5HI 



Create WebLogic Configuration 

Specify the directory where the WebLogic configuration should be created. 
Click the "Create" button to create the WebLogic configuration. 



Configuration Summary 
r~l Template 
3 Ell Server 

myserver 



Configuration Details 
Attribute Value 
Name Basic WebLogic Server Domain 

Description Create a basic WebLogic Server domain without installing s 
Author BEA Systems, Inc. 

Location C:\bea\weti|ijgii:31\common\terriplates\domains\wls.jar 



]0 



Configuration Location 
Browse C:\bea\user_projecls\mydomain 



Configuration Name: my domain Create 



Previous 



Using the Console Mode Installer 

The console mode installer does not use a graphical interface, and many 
people think it's harder to use than the GUI installer. You can use the console 
mode installer in Windows or UNIX. If you're using a UNIX system that doesn't 
have access to a GUI, you must use the console mode installer. 
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Two types of console mode installers are available, and which type BEA 
Systems provides depends on the version of the operating system you're 

ou have UNIX, the extension of your installer can be .bin or .jar. For 
it's .exe. The following sections describe how to install under UNIX 
and Windows operating systems. 



Installing under UNIX 

If your system uses UNIX, your installer could have a .bin or a .jar file name 
extension. If your installer has the .bin extension, that means the installer 
includes Java Development Kit (JDK), as described earlier. Installation files 
ending in .jar do not include JDK. 

Installing With a .bin file 

If you have an installer file that ends in .bin, how you install the file depends 
on whether you downloaded the installation file from the Internet or have it 
available on CD. 

To install your .bin file if you have it available on a CD, follow these steps: 

1. Log on to the system as the user who will run WebLogic Server. 

2. Open a command-line shell. 

3. Insert the WebLogic CD in the CD-ROM drive. 

4. Change to the webl ogi c pi atf orm801 directory on the CD. 

5. Invoke the following command: 

./filename. bin -mode=consol e 

where f1 1 ename .bin is the name of the installer. 

The installation program installs WebLogic. 

If you downloaded the .bin file, the steps are slightly different: 

1. Log on to the system as the user who will run WebLogic Server. 

2. Open a command-line shell. 

3. Go to the directory where you downloaded WebLogic and invoke the 
following two commands: 

chmod a+x filename.bin 
./filename. bin -mode=consol e 



where f1 7 ename . b i n is the name of the installer. 

The installation program installs WebLogic. 
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Installing With a .jar file 

If jou have an installer file that ends in .bin, follow these steps: 



on to the system as the user who will run WebLogic Server. 

2. Open a command-line shell. 

3. Include the bi n directory of your JDK at the beginning of the PATH 
variable: 

PATH=javapath/bin:$PATH 
export PATH 

where java path is the full path to your JDK directory. 

4. Change to the directory that contains the .jar file. 

5. Do one of the following: 



If you're using JDK 1.3.1_03 or higher, type the followin; 




java -jar filename. jar -modi 


3=consol e 




where fi 7 ename . j a r is the name < 


Df the installer. 





• If you're using the AIX version of UNIX, type the following: 



java -cl 
com 


asspath filename. jar 

. bea .installer.BEAInstallController 




where fi 7 


ename. jar 


is the name 


of the installer. 





The installation program installs WebLogic. 



Installing under Windows 

If you have an install file that uses the .exe file extension, WebLogic assumes 
that you already have Java installed and set up in your system path. How you 
install the file depends on whether you downloaded the installation file from 
the Internet or have it available on CD. 

If you're installing from a CD-ROM, follow these steps: 

1. Log on to the system as the user who will run WebLogic Server. 

2. Open a command-prompt window. 

To do so, choose StartOAll ProgramsOAccessoriesOCommand Prompt. 



Chapter 2: Installing WebLogic Server 



ipBooks 

4. Invo 



3. Go to the webl ogi c pi atform801 directory on the CD-ROM. 

If you obtained WebLogic from the Web, go to the directory where you 
nloaded WebLogic. 



Invoke the following command: 

net_pl atf orm801_3i n32 . exe -mode=consol e 

The installation program installs WebLogic. 
If you downloaded WebLogic from the web, follow these steps instead: 

1. Log on to the system as the user who will run WebLogic Server. 

2. Open a command-prompt window. 

3. Go to the directory where you downloaded WebLogic. 

4. Invoke the following command: 

filename mode=consol e 

where fi lename is the name of the file that you downloaded. 



Using the Silent Mode Installer 

Silent mode installation works much like the GUI installation program. The 
main difference is that the silent mode installer gets all its input from a file, 
whereas the GUI installer gets all its input from the user. Silent installation 
can be used under Windows and UNIX. 

Silent installation is valuable when you must perform the same installation on 
many different computers. 

Using the silent mode installer involves two main steps: 

1. Create an installer properties file. 

2. Use the installer properties file to invoke the installer. 

You perform Step 1 once and then repeat Step 2 on every computer on which 
you want to install the server. 

In this section, you see how to carry out these two steps. I begin by showing 
you how to create an installer properties file, sometimes referred to as a tem- 
plate file. 
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Creating a template file 



using the silent method, you must create a template file. The tem- 
contains all the setting information that you would normally provide 
to the GUI installation utility These settings are all expressed inside XML 
tags. Make sure that you do not modify the structure of the XML tags. 

Follow these steps to create a template file: 

1. Obtain a template file from the following location: 

http://e-docs.bea.com/wls/docs81/install/instsil. 
html#1042712 

An example template file is also shown later in this chapter. 

2. Save the contents of the template file to a file named silent.xml. Place 
this file in the directory containing the WebLogic Server installation 
program. 

3. Modify your template file so that the settings make sense for your 
needs. 

See Table 2-1 for a list of settings. 



Table 2-1 Mandatory Silent Mode Installation Properties 



Property 


What It Is 




BEAHOME 


The 


BEA home directory. This directory holds 




common files used by multiple BEA produ 


cts, such 




as the license file. 





RUN JOMA I N_WI ZARD Specifies whether Configuration Wizard should be 

run. If True, the wizard is run; if False, it is not. If you 
choose to run Configuration Wizard, you must spec- 
ify the data values used by the wizard, as detailed in 
Table 2-2. 

USER_INSTALL_DI R The directory into which you will install WebLogic. 



Only a few properties need to be set in the template file; these are shown in 
Table 2-1. If you choose to control Configuration Wizard with the template file 
(by setting RUN_DOMAIN_WIZARD to True), the number of properties you need 
to set suddenly becomes much larger. The Configuration Wizard properties 
you can set in the template file are detailed in Table 2-2. 
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Table 2-2 


Configuration Wizard Properties 




What It Is 


JI\o unCT KIAMr nD 

A DMTn_H 0 S T_N A M EJD R_ 


1 P The Administration Server name or IP address. 


ADMIN_LI STEN_P0RT 


The port at which the Administration Server 
listens. 


C_domai nName 


The beginning of a domain name specification. 
One or more of these attributes can be specified 
to create domains. (On UNIX systems, do not 
include spaces in the domain name.) 



C_password The password to be used with the administrative 



userforthis server. The password must contain 



at least 8 characters but no more than 
use spaces or XML reserved characte 
as <, >, {, or}. 


20. Do not 
rs such 


C_ 


_serverl_isten Address 


The DNS name 


or system IP for the se 


r ver. 


C_ 


_serverl_istenPort= 


Used to specify the server listen port. 1 


vlost web 



servers use port 80. WebLogic uses port 7001 by 
default. 



C_serverName 


Used to specify the server name forthe specified 
domain. Do not include spaces in the server 
name. 


C_serverSSLLi stenPort= 


Used to specify the SSL server listen port, which 
is used for HTTPS connections. Most web 
servers use port 443. WebLogic uses port 7002 by 
default. 


C_username 


A user name to start the server and access 
Administration Console. Do not use spaces or 
XML reserved characters such as <, >, {, or }. 


CI usterMCAddr 


The multicast IP address that Administration 
Server uses to communicate with clustered 
servers. WebLogic uses 237.0.0.1 by default. 


CI usterName 


Name of the cluster (if any) to create. Do not 
include spaces in the cluster name. 


CI usterPort 


The multicast port that Administration Server 
uses to communicate with clustered servers. 
WebLogic uses port 7777 by default. 



(continued) 
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cl uste 



cl US" 
data 



erServers 
group 



What It Is 



If the SERVER-RUN-AS parameter is set to Admin 
Server with Clustered Managed Server(s), specifies 
the configuration of the cluster. For each server in 
the cluster, you must specify the following three 
items: cl usterServerRegName (the name of the 
server as registered with Administration Server), 
clusterServerHostIP (the DNS name or IP 
address of the machine), and cl usterServer 
Li stenPort (the server listening port). 



DB^EMAI L_ADDRESS The e-mail sending address used by WebLogic 

Integration. 



DB_EMAI L_H0ST 


The default e-mail server used by WebLoc 
Integration. 


ic 


domai n . di rectory 


The full path to the domain directory. On UNIX 
systems, do not include spaces in path names. 


I N ST A L L_NT_S E RV I C E 


Used to specify whetherthe server should be 
installed as a service when installing on a Windows 


system. Possible values are yes and no. 




INSTALL_WINDOWS_ 
STARTUP_MENU 


Used on a Windows system to specify whether a 
WebLogic option should be installed on the 
Windows Start menu. Possible values are yes and 
no (the default). 



MANAGED_SERVER_ The machine or server name as registered with 

REGI STERED_NAME_ Administration Server. 

IN_ADMIN 



managedServers Ifthe SERVER-RUN-AS parameter is setto Admin 

data group Server with Managed Server(s), specifies the 

configuration of the managed servers in the domain. 
For each managed server, you must specify four 
items: managedServerRegName (the name of the 
server as registered with Administration Server), 
managedServerHostIP(theDNSnameorlP 
address of the machine), managedServer 
Li stenPort (the server listening port), and 
managedServerSSLLi stenPort (the secure 
listening port). 



sel ectedJar The full path and file name of the template JAR file 

to be used by Configuration Wizard to create the 
domain and configure the server. 
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R- RUN - AS Determines the server configuration created by 

Configuration Wizard. Possible settings are Single 
Server, Admin Server with Managed Server(s), 
Admin Server with Clustered Managed Server(s), 
and Managed Server (with owning Admin Server 
configuration). 



To specify a setting for a property, you use the property name and 
value as an XML tag. For example, the following sets a value for the 

USER_INSTALL_DIR property: 

<data - va 1 ue name="USER_I NSTALL_DI R" val ue = "C : \bea \webl ogi c81 " 
/> 



Using the property types shown in Table 2-1, you can create a properties file 
that the installer will use. An example of a Windows silent.xml file is shown in 
Listing 2-1. 



Listing 2-1: Silent Install Properties File 



<?xml vers i on=" 1.0" encoding="UTF-8"?> 
<domai n- tempi ate-descriptor> 

"BEAHOME" value="C:\bea" /> 

" USER_I NSTA L L_D I R" val ue="C : \bea\webl ogi c81 " /> 
" RUN_D0MAI N_WI ZARD" val ue="fal se" /> 

"domain.di rectory" val ue="C: \bea\user_domai ns\mydomai n" /> 
"C_domai nName" val ue="mydomai n" /> 

"C_serverName" val ue="myserver" /> 

"C_username" val ue="system" /> 

"C_password" val ue="webl ogi c" /> 

"C_serverListenAddress" value="" /> 
"C_serverLi stenPort" val ue="7001 " /> 
"C_serverSSLLi stenPort" val ue= " 7002 " /> 
"CI usterName" val ue="mycl uster" /> 

"CI usterPort" val ue= " 7777 " 7> 

"sel ectedJar" 

val ue="C: \bea\webl ogic81\common\templ ates\domains\wl s . jar" /> 
<data-value name=" INSTALL_NT_SERVICE" value="no" /> 
<data-value name=" I NSTA L L_WI NDOWS_STARTU P_MENU " value="no" /> 
<data-value name="DB_EMAI L_H0ST" val ue="myserver" /> 
<data-value name="DB_EMAI L_ADDRESS" val ue="name@bea . com" /> 

</input-fields> 

<7domain-templ ate-descri ptor> 



<i nput-f i el ds> 


<data 


■val ue 


name : 


<data- 


■val ue 


name : 


<data- 


■val ue 


name : 


<data 


■val ue 


name : 


<data 


■val ue 


name : 


<data 


■val ue 


name : 


<data- 


■val ue 


name : 


<data- 


■val ue 


name : 


<data- 


■val ue 


name : 


<data- 


-value 


name : 


<data 


■val ue 


name : 


<data 


val ue 


name : 


<data 


■val ue 


name : 


<data- 


-value 


name : 
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Now that you've created a properties file to be used as a template for your 
installation, you're ready to invoke the silent installer program and perform 
the actual installation. You can perform the silent installation once or many 
times. (The silent mode was designed to be used when you want to perform 
the same installation more than once.) 

The instructions for how to start the silent mode installation program are 
slightly different between UNIX and Windows. The next two sections explain 
invoking the silent mode installer in both UNIX and Windows. 

If you're using the silent mode installation under Windows, follow these steps: 

1. Log on to the Windows system with an account that has administrator 
rights. 

2. Open a command-prompt window. 

3. If you're installing from a CD-ROM, go to the CD-ROM directory. If you 
obtained WebLogic from the web, go to the directory where you 
downloaded WebLogic. 

4. Invoke the following command: 

filename.exe -f f ul 1 path\si 1 ent.xml 

where f1 1 ename . exe is the name of the installer and full path is the 
path to your installer properties file. 

The installation program installs WebLogic. 
If you're using the silent mode installation under UNIX, follow these steps: 

1. Log on to the UNIX system as the target user. 

2. Open a command-prompt window. 

3. If you're installing from a CD-ROM, go to the CD-ROM directory. If you 
obtained WebLogic from the web, go to the directory where you 
downloaded WebLogic. 

4. Invoke the following command: 

sh filename.bin -f f ul 1 path/si 1 ent.xml 

where f 7 lename.bin is the name of the installer and ful 1 path is the 
path to your installer properties file. 

The installation program installs WebLogic. 
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In This Chapter 

Writing a startup script 

Starting WebLogic from the Start menu 

Starting WebLogic automatically 



IX ou normally don't think much about starting application programs. You 
simply click the appropriate icon and the application starts. If you want, 
starting WebLogic can be this simple. However, WebLogic also offers several 
other ways to start the server: from a script and from the Windows Start 
menu. 



Writing a WebLogic Startup Script 

One of the most common ways to start WebLogic Server is by using a startup 
script. A startup script is nothing more than an ordered list of commands that 
would normally be issued at the Windows or UNIX command prompt. Starting 
WebLogic Server from an existing startup script has several advantages: 

There is no need to enter the admin ID and password each time. 

Other related commands, such as mapping network drives, can automat- 
ically be performed as part of the script. 

The script can be started easily by other automated processes. 

However, using a custom startup script has some potential disadvantages, 
such as the following: 
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f" If the admin password is embedded in the script, the script is less 
secure than the supplied script. 

kes time to properly create a startup script. 

user must be logged on to the server to run the startup script. 



You begin finding out about startup scripts by examining the standard 
startup script that WebLogic creates for new server instances. 



The standard startup script 

Fortunately you do not need to build your startup script from scratch. Every 
time that you create a new server instance, as described in Chapter 4, a stan- 
dard startup script is created for you. You can modify this script as you see 
fit. The standard startup script is named startWebLogic.cmd if you're running 
Windows and startWebLogic.sh if you're running UNIX. The contents of the 
Windows and UNIX startup scripts are similar. Listing 3-1 shows an example 
of the standard startup script generated by WebLogic for the Windows oper- 
ating system. 



Listing 3-1 : Typical Windows WebLogic Startup Script 

echo off 
SETLOCAL 

@rem Set SERVER_NAME to the name of the server you want to 
@rem start. 

set SERVER_NAME=myserver 

@rem Set WLS_USER equal to your system username and 

@rem WLS_PW equal to your system password for no username 

@rem and password prompt during server startup. Both are 

@rem required to bypass the start prompt. This is not 

@rem recommended for a production environment. 

set WLSJJSER= 

set WLS_PW= 

@rem Set Production Mode. When this is set to true, 
@rem the server starts in production mode. When 
@rem set to false, the server starts in development 
@rem mode. If it is not set, it will default to false, 
set STARTMODE= 

@rem Set JAVA_0PTI0NS to the Java flags you want to pass to 
@rem the vm . i.e.: 

@rem set JAVA_OPTIONS=-Dwebl ogi c . attri bute=va 1 ue 
@rem -Dj a va . attri bute=val ue 
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set JAVA_0PTI0NS=- 

Dwebl ogi c . securi ty . SSL . trustedCAKeyStore=C : \bea\ 
weblogic81\server\lib\cacerts 



et JAVA_VM to the Java virtual machine you want to run. 
@rem For instance: 
@rem set JAVA_VM=-server 
set JAVA_VM= 

@rem Set MEM_ARGS to the memory args you want to pass to 

@rem Java. For instance: 

@rem set MEM_ARGS=-Xms32m -Xmx200m 

set MEM_ARGS= 

@rem Call Weblogic Server 

cal 1 "C : \bea\webl ogi c81\ serve r\bi n\startWLS . cmd" 
ENDLOCAL 



The startup script is not too difficult to understand. Lines that begin with 
@rem are remarks, or comments, added so you can understand what the dif- 
ferent command lines do. The lines that do not begin with @rem are inter- 
preted by WebLogic and are used to start the server. 

Through the startup script, you set environment variables that control the 
launch and runtime operation of WebLogic Server. To create a customized 
startup script, you begin by modifying these variables in the standard script. 
I show you how to do this in the next section. 

If additional commands must be executed before the server starts, simply 
modify the script to include the commands. A script is executed line by line, 
so make sure that the commands appear in the script file before the end, 
where the startWLS.cmd file is invoked. (This is the script command to start 
WebLogic Server.) 



Constructing your ortn startup script 

In the preceding section, you saw that WebLogic creates a standard script 
that you can modify. In this section, you find out how to set the various envi- 
ronment variables in the script. The first step in modifying a startup script is 
to load it into a text editor. A startup script doesn't require a special program 
for editing; it is nothing but a plain text file. In Windows, you can do your 
editing in a program such as Notepad. In UNIX, you can use a program such 
as vi or pico. However, you're not limited to using these programs; any text 
editor will suffice. 
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If you're not familiar with the UNIX environment, you will probably find the vi 
editor confusing. The pico editor more closely resembles Windows Notepad, 
e pico editor from UNIX, you type the pico command followed by 
of the file you're editing. For example, the following command edits 
the web.xml file using pico as your editor: 



pico web.xml 

Now that the startup script is opened, you can make your desired changes. 
Table 3-1 lists some of the environment variables you can modify. 



Table 3-1 



STARTMODE 



WLSJJSER 



WebLogic Environment Variables 



Variable Name 


What It Is 






JAVA_0PTI0NS 


The Java command-lin 


e options for running th 


e server. 


JAVA_VM 


The Java argument spf 

as -server or -cl i e 


;cifying the VM to run such 
nt (hotspotis deprecated). 


MEM_ARGS 


The variable to override the standard memory 
passed to Java. 


arguments 



The operating mode for the server. Specify True for 





production mode servers and False for develo| 


:ment 




mode. 






WLS_PW 


The WebLogic user password used to start the 


i server. 



The WebLogic user ID used to start the server. 



Usually, you will not want to change the default virtual machine that Java is 
using. Java achieves performance gains by compiling Java instructions into 
the native instruction set of the computer. If you specify the -classic option 
for JAVA_VM, no compiling is used. If you specify the -server or -cl i ent 
option, a compiler optimized for server or client operations, respectively, is 
used. There's no reason to ever run WebLogic using the - client option. 

In Table 3-1, look at the STARTMODE variable and the mention of development 
and production modes. When you want to know whether something is work- 
ing properly, use development mode because it helps you track down prob- 
lems. Production mode reports fewer errors and generally runs faster. 

A side effect of development mode is that you'll need to clear the logs more 
often and pay more attention to your server. Production mode also preloads 
more of the server, so if you're restarting the server frequently, you'll want to 
use development mode. 
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You can also specify the user ID and password when staring the server. To 
specify the user information, you should use the WLS_PW and WLS_USER vari- 
is will prevent WebLogic from prompting you each time it starts. 
OPTIONS variable allows you to pass additional parameters to the 
Java virtual machine. The MEM_ARGS variable allows you to request additional 
memory. The format for MEM_ARGS follows: 




MEM_ARGS=-Xmsl28m -Xmx512m 

This command specifies 128MB of initial memory size and 512MB as the max- 
imum memory size. 

If you get out-of-memory errors in WebLogic, you should adjust the MEM_ARGS 
variable. 

Now that you have seen how to start WebLogic Server using a startup script, 
I will now show you how you can easily start WebLogic Server from the 
Windows Start menu. 



Starting WebLogic from the 
Windows Start Menu 

You use the Windows Start menu to start most Windows applications. When 
you choose to start WebLogic from the Start menu, a default script is created 
for you and a shortcut to that script is placed in the Start menu. 

Starting WebLogic Server from the Start menu has a few immediate advan- 
tages. Perhaps the biggest advantage is that this method is simple. Another 
benefit is that if you've defined several different instances of your server, you 
can see them all in a single place. All WebLogic Server instances are started 
by choosing StartOBEA WebLogic Platform 8.10User Projects. 

To start WebLogic from the Start menu, you must specify — when you config- 
ure your server — that you want to use the Start menu. For more information 
on setting up WebLogic Server instances, refer to Chapter 4. 

Starting WebLogic from the Start menu also has a few disadvantages. For 
example, you can't use the Start menu to automatically start the server when 
the computer boots. (For this reason, using the Start menu is considered a 
manual method of starting WebLogic Server.) A related drawback is that a 
user must be logged on to the system before the server can be started. 
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m've read about two methods of starting WebLogic Server: through a 
startup script and from the Windows Start menu. Both methods require you to 
be logged on to the system to start WebLogic Server. When you're using 
WebLogic Server in a production environment, you normally want the server to 
start automatically as part of the overall machine booting process. After all, it 
could be that this machine's only purpose is to run WebLogic Server. In this 
section, I describe two methods you can use to automatically start WebLogic 
Server at machine startup, without any manual intervention on your part. 

The first automated method works only on the Windows platform. You can 
configure WebLogic to run as a Windows service. Windows services run in the 
background, out of the direct reach of users who may be logged on to the 
system. Additionally, services can be configured to start when the machine is 
first started. 

The second automated method that can be used works only on the UNIX plat- 
form. UNIX programs that run in the background, independent of the current 
user, are called daemons. By configuring WebLogic to run as a UNIX daemon, 
your server starts automatically and is not directly affected by users logging 
on to and off the system. 

Running WebLogic Server by one of these automated means makes server 
startup, shutdown, and error handling less obvious to system users, so these 
methods are more suitable for a production environment. When you're still 
developing your application and will likely be starting and stopping your 
server often, you'll find that using the Start menu or a startup script is much 
more convenient than running either a UNIX daemon or a Windows service. 



Configuring WebLogic as a 
Windows service 

The most common way to start WebLogic Server in a Windows production 
environment is as a Windows service. In this section, you find out how to 
configure WebLogic Server to run as a Windows service, as well as how to 
start and stop a Windows service. Starting WebLogic Server as a Windows 
service has several advantages: 

Your WebLogic service starts automatically when Windows loads. 

V No user needs to be logged on for WebLogic Server to be running. 

WebLogic Server can be stopped and restarted by any program designed 
to work with Windows services. 

i>* WebLogic Server runs out of direct reach of the current user. 
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The only drawback to running WebLogic Server as a Windows service is that 
debugging server applications can be more difficult because the current user 
ave direct access to the running server. (This is why you should run 
Server as a service only on a production machine, not on a devel- 
opment machine.) 



Next, you configure WebLogic Server as a Windows service. You see how to 
do this for a new WebLogic Server instance as well as an existing WebLogic 
Server instance. Finally, you see how to remove WebLogic as a service. 



Configuring a new WebLogic Seri/er instance 

Configuring a WebLogic Server instance to run as a Window service is easy. 
When you first configure a server instance using Domain Configuration 
Wizard (see Chapter 4), you are given the option of making this server a 
Windows service. If you select the option to install your server instance as 
a service, your WebLogic Server will be running in the background the next 
time you reboot the machine. 

To configure WebLogic Server to run as a service, you must be a Windows 
user with administrative privileges. 

Configuring an existing WebLogic Server instance 

If you have an existing WebLogic Server instance that you'd like to configure 
to run as a Windows service, you must run a command-line utility. Follow 
these steps: 

1. Open a command-prompt window. 

To do so, choose Starts All ProgramsOAccessoriesCCommand Prompt. 

2. Switch to the webl ogi c\bi n directory. 

3. Run the install command, specifying the name of the WebLogic Server 
instance that you would like to configure as a service. 

For example: 

c : \webl ogi c\bi n> install -name yourWebLogi cServer 

To configure a WebLogic Server instance to run as a service, you must 
be logged on to Windows using an account that has administrative privi- 
leges. Replace you rblebLog i cServer with the name of your server. 

Removing a WebLogic Server instance 

Configuring a WebLogic Server instance as a Windows service doesn't have 
to be a one-way operation. If you ever need to turn off the instance, so that it 
doesn't operate as a service, follow these steps: 
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1. Open a command-prompt window. 

Choose StartOAll ProgramsOAccessoriesOCommand Prompt, 
ch to the webl ogi c\bi n directory. 



Run the remove command, specifying the name of the WebLogic 
Server instance that you want to remove. 

For example: 

c : \webl ogi c\bi n> remove -name yourUebLogicServer 

To change how a service operates, you must be logged on to Windows 
using an account that has administrative privileges. Replace 
yourhlebLogi cServer with the name of your server. 

Starting and stopping your service 

If you're already familiar with how to manage Windows services, you'll 
find that WebLogic service administration is similar. To start or stop your 
WebLogic service, you use the Services applet from the Control Panel, which 
is shown in Figure 3-1. 
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The following steps show you how to start and stop your service: 



DropBocte 



ose StartOControl Panel, 
the Administrative Tools icon. 
3. Double-click the Services icon. 



A listing of all services configured on this system is displayed. All 
WebLogic services begin with beasvc. 

4. Right-click your WebLogic service. 

A menu appears that allows you to start or stop your service. 

The Properties menu option allows you to configure the start type for your 
service, which determines whether the service should be started automati- 
cally when Windows starts. The default setting for this option is Automatic 
Startup When Windows Starts. 



Running WebLogic as a UNIX daemon 

If you want your WebLogic Server to start automatically under UNIX, you 
must configure the server to run as a UNIX daemon. A UNIX daemon process, 
like a Windows service, is a program that runs in the background. 

Starting WebLogic Server as a daemon has the following advantages: 

f This startup method is compatible with the UNIX operating system. 

Your WebLogic service starts automatically when UNIX loads. 

No user needs to be logged on for WebLogic Server to be running. 

f Your WebLogic service starts and stops in a way that is consistent with 
other UNIX daemon processes. 

*<" WebLogic Server runs out of direct reach of the current user. 

The last advantage in the list, however, can also be a disadvantage. Having 
direct access to the running server can be helpful when debugging the 
server. 

To set up your WebLogic Server instance to run as a daemon, do this: 

1. Change to the superuser by issuing the s u command and entering the 
root password. 

To set up WebLogic Server to run as a daemon, you must have root 
access. 



Part I: Installing and Configuring WebLogic 



I— ^ ■ This i 

pBocte 



2. Create a daemon script. 

This script will start and stop your WebLogic Server instance by calling 
tartup script that you created earlier in the chapter. Listing 3-2 
s an example daemon script; note that you need to supply the com- 
plete path to your own script. The name of this script should reflect the 
server instance it was associated with. For this example, I assume that 
you named it myserver. 

3. Place this script in the / etc/rc.d/init.d/ directory. 

4. Add a symbolic link to this script from the appropriate run levels. 

This will cause your script to be executed both when the machine is 
starting up and shutting down. Inside / etc/rc.d/rc5.d/ and 
/etc/rc.d/rc3.d/, you must place a symbolic link using the In -s 
command. You must start the name of your link with an S, which means 
startup. The command you would use for the name myserver follows: 

In -s /etc/rc.d/init.d/myserver /etc/ rc . d/rc5 . d/Smyserver 



5. Create a kill script. 

This is accomplished by placing a link, which starts with K, in the 

/etc/ rc . d/rc6 . d and /etc/ rc . d/ rcO . d directories. You would use a 
command such as 

In -s /etc/rc.d/init.d/myserver /etc/rc . d/rc5 . d/Kmyserver 

The preceding directory structure was taken from Red Hat Linux. Other 
UNIX implementations may vary. 



Listing 3-2: Sample Daemon Script 



#!/bin/sh 

#see how we were called 

case in 
start) 

# ... enter the complete path to your startup script here 
stop ) 

# ... enter the complete path to your shutdown script here 



esac 
exit 0 



Now that you have created the appropriate links, your server should start in 
the background the next time you start the machine. 
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In This Chapter 

Configuring at the domain, cluster, server, or machine level 

Configuring with Administration Console 

Working with network channels and address points 

Presenting Node Manager 

Setting up and starting Node Manager 

Monitoring the server with Administration Console 



Configuration and administration are two important topics when dealing 
with an application server such as WebLogic. In other chapters, you find 
out how to perform tasks that are usually carried out while you're developing 
a web application. Configuration and administration, however, are ongoing, 
day-to-day operations. 

Common configuration tasks for WebLogic include adding users, defining net- 
work channels, defining access points, setting up security, and creating server 
instances. Administration involves checking the health of your server and 
ensuring that everything is properly configured. In this chapter, you find out 
how to perform all these tasks. 



Domains are an important WebLogic feature. The next section describes 
domains as well as other logical structures in WebLogic. 
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When configuring or administering WebLogic, you're working at one of the 
following four levels: 

Domain. A collection of servers and clusters. The domain is the highest 
administrative level in WebLogic. 

V Cluster. A collection of servers that acts like one server. 

Server. An instance of WebLogic running on a machine. 

Machine. An individual computer that may be running one or more 
servers. 

It is important that you understand these levels so that you understand the 
scope of any changes you may make. 

A machine is the physical hardware on which you run WebLogic. When you 
install WebLogic, you install it on a machine. A server is defined by an installa- 
tion, or instance, of WebLogic. Most times, a one-to-one ratio exists between 
machines and servers (in other words, one machine has one WebLogic Server 
installed on it), but you could install multiple servers on a single machine, if 
you needed to. You should always remember the distinction that WebLogic 
makes between servers (which are virtual or logical) and machines (which 
are physical). 

A cluster is a group of servers that acts as one single server. The two main 
reasons for using a cluster are reliability and scalability. A cluster can be 
more reliable than a single server. If a single server goes down, your web 
application is no longer available to your users. If you have more than one 
server running in a cluster, however, one server can go down without taking 
the entire web application down with it. 

A cluster can also make your web application more scaleable. Rather than 
buying bigger and more expensive machines to house your system, you can 
simply add additional services. As new requests come in from users, the clus- 
ter will assign each individual request out to one of the servers in the cluster. 
To learn more about clusters, refer to Chapter 18. 

A domain is the highest administrative level in WebLogic. It is simply a 
number of clusters and servers grouped together for administrative pur- 
poses. You will likely use more than one domain if you have a large number 
of servers and clusters. For most applications, a single domain will suffice. 
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Do not confuse a WebLogic domain with an Internet domain name. There is 
no.connection between the two. 
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Usinq Administration Console 




Most of your configuration activities will take place at the server level, inside 
Administration Console. Administration Console allows you to configure one 
server at a time. You access Administration Console through a web browser, 
just like you do your actual web site. Because of this, you must make sure 
that your web server is started before trying to use Administration Console 
to configure it. 

Because Administration Console is accessed through a web browser, you can 
easily configure your server from anywhere on the Internet. 



Loqqinq on to Administration Console 

Before you can administer a server, you need to know how to access and log 
on to Administration Console. Follow these steps: 



1. Make sure that WebLogic Server is running. 

See Chapter 3 if you need a refresher on how to start your server. 

2. Start your favorite web browser. 

3. In the browser, type the URL of your server's Administration Console. 

If you're running the browser and the server on the same computer, 
use http://localhost:7001/console/for the URL. If you're 
running the browser and the server on different computers, use 
http : / / computername : 7001/consol e/, where computername is 
the name of the computer running WebLogic Server. The WebLogic 
login screen appears, as shown in Figure 4-1. 

Note: If you didn't install WebLogic using the default settings and 
WebLogic listens to a different port than 7001, you must replace 7001 
with the port number you specified during installation. 

4. Type your username and password. 

If you're trying to administer one of the sample servers provided by 
WebLogic, your username is i nstal 1 admi ni strator and the password 

is i nstal 1 admi ni strator. 
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Because Administration Console enables you to configure your server 
from anywhere on the Internet, make sure that you secure it by using a 
username and password that are not easily guessed. It's always a good 
idea to have a password that is not in the dictionary. A password with 
more than eight characters that includes numerals is ideal. 

5. Click Sign In. 

Administration Console appears, as shown in Figure 4-2. 



Using Administration Console 

Now that you're logged on to Administration Console, you're ready to config- 
ure your server. Administration Console is divided into two major sections, 
similar to many other Windows tools, such as Windows Explorer. On the left 
side of the screen is a hierarchical depiction of the major configuration areas, 
with each configuration area displayed as a folder. If a folder has a plus sign 
to its left, you can click it to show more detail. (To hide the details, click the 
minus sign to the left of the folder.) 
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The right side of the screen contains information and options related to what- 
ever you selected on the left side of the screen. 

Administration Console offers a wide range of choices, which at first glance 
can be overwhelming. Fortunately, you need to concern yourself only with 
configuration areas corresponding to the parts of WebLogic that you're using. 

Table 4-1 summarizes the configuration areas supported by Administration 
Console. Also listed is the chapter to turn to for more information on each of 
these areas, with two exceptions: Domain Log Filters and Tasks, which are 
explained next. The Domain Log Filters configuration area is similar to corre- 
sponding features in a regular web server. It allows you to specify the type of 
information that should be maintained in the log files for the domain. The 
Tasks item is basically a way to review the most recent actions taken in 
Administration Console. When you click this item, WebLogic displays the 
completed tasks in the right portion of the screen. You can then click one of 
the tasks listed and see a description of what the task involved and when the 
task was completed. 
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Servers 



Major WebLogic Configuration Areas 



ration Area What It Does 



See 



Configures the servers that you Chapter 5 
have set up. 



Clusters 



Creates and manages clusters. 
From this area, you can assign 
servers to clusters. 



Chapter 16 



Machines 


Configures machines using 
Node Manager. 


Chapter 4 
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Creates and configures network 
channels that allow users to 
connect to your server in a variety 
of ways. 


Chapter 4 




Deployments 


Configures 


a 


nd deploys your EJBs. 


Chapter 6 




Services 


Configures a variety of tools such 
as JDBC, JCOM, JMS, and JTA. 


Chapter 12 1 
Chapter 15 1 
Chapter 14 1 


:JDBC); 

:jms»; 
:jta» 


Security 


Maintains and manages the 
security of your site. 


Chapter 18 




Domain Log Filters 


Allows you to select which server 
log entries are passed to the domain 
log. You usually keep the default 
settings. 






Tasks 


Displays a list of tasks that were 







recently carried out by WebLogic 
administrators. 



Defining NeWork Channels 

Network channels establish a connection between WebLogic Server and the 
outside world. By using network channels, WebLogic can support a variety 
of protocols. This means that you don't need to be aware of the differences 
between these protocols when you create your web application. Instead, you 
create your application to be compatible with WebLogic and leave the proto- 
col infrastructure to the network channels. 

After your web application is ready, you simply make it available over what- 
ever protocols you want. If you want to add additional protocol support later, 
you just add additional network channels. 
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Network channels allow you to specify how TCP/IP ports on a computer are 
connected to the services provided by WebLogic. Each network channel 
e following attributes about a connection to WebLogic Server: 



protocol (for example, HTTP, HTTPS, T3, T3S, or COM) 
V The TCP/IP port to listen on 
i>* Whether or not tunneling is supported 

v 0 Whether the connection is to clients or other WebLogic Servers 

Network channels are created using the Network Access Point section of 
Administration Console. 



WebLogic uses the terms network access point and network channel inter- 
changeably — sometimes even on the same screen, as shown in Figure 4-3. 
I refer to them as network channels. 



Before you can work with a network channel, you must create one. Follow 
these steps: 

1. Log on to Administration Console. 

2. On the left side of the Administration Console screen, click the 
Servers folder, and then click your server. 

The information on the right side of the screen changes to reflect the 
configuration area you selected. 

3. Click the Protocols tab and then click the Channels subtab. 

The screen shown in Figure 4-3 appears. 

4. Click the Configure a new Network Channel link. 
The screen shown in Figure 4-4 appears. 

5. Configure your network channel. 

Notice the caution icon. It simply means that if you make a change to the 
option, you might have to restart the server. 

At a minimum, you should specify a listen port and address. (You may 
have to scroll the screen to see them.) Listen port is the regular port 
used when a browser accesses a URL that starts with http. SSL listen 
port is used when a secure page is requested with a URL that starts with 

https. 

6. Click Create. 

You've created the channel. 
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Network Channels are an optional feature that you can configure to segregate a 
WebLogic Server instance's network traffic over different Network Interface 
Cards (NICs), and to allow the server to listen for requests on multiple ports. A 
channel can be assigned to only one WebLogic Server instance (server). Each 
server can have multiple channels. Each channel assigned to a specific server 
must have a unique combination of Protocol, Listen Address and Port. 

When one or more network channels are configured for this server, this 
Network Channels page displays key information about each of them. To 
create a network channel, click the Configure a new Network Channel... link. 
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Ss Name: MyNetwork Channel 

The name of this network channel. 

A Protocol: |t3 [&] 

The protocol this network channel should use for connections. 

Listen Address: | | 

The IP address or DNS name this network channel uses to listen for 
incoming connections. A value of null indicates that the network 
channel should obtain this value from the server's configuration (located 
under your server's Configuration > General tab). 

A Listen Poit: 



7001 



<L 



The default TCP port (between 1 and 65534) this network channel uses t 



X> Internet 
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Introducing Node Manager 

ipBooks 

Earlier in 




gic terminology, a node is an individual element of a cluster. 
Earlier in the chapter, I mentioned that clusters are made up of individual 
WebLogic Servers. Thus, nodes and servers are essentially synonymous. In 
addition, because a one-to-one relationship often exists between servers 
and machines, the term node can be used also to refer to an individual 
machine. A node controlled by Node Manager is called a managed server. 

You use Node Manager only when you need to manage a large number of 
nodes. Node Manager can be somewhat tricky to configure because it runs 
on multiple machines and relies heavily on script files and environmental 
variables. If you're going to be working with only a single WebLogic Server, 
you don't need to concern yourself with Node Manager. 

Node Manager has the following two main components: 

V Node Manager, which runs on each managed server 

Administration Server, which runs on one computer and coordinates all 
Node Managers 

Under a Node Manager system, you have a network of computers running 
Node Manager and a single machine running Administration Server. Node 
Manager is most useful when you're using a cluster (a group of servers that 
appear as one server). By having more than one server, your system gains 
greater reliability and performance. Clustering is covered in Chapter 16. 

One of the jobs of Administration Server is to restart Node Manager comput- 
ers when they lock up, so it's a good idea to make sure that Administration 
Server is running on a computer that's not also running Node Manager. If 
Administration Server was running on a server that crashed, Administration 
Server would be down as well. And because Administration Server can't 
restart itself, it would be unable to restart the server. 

In particular, Node Manager allows you to 

f" Start remote managed servers 

f* Restart managed servers that have shut down unexpectedly or crashed 

Automatically monitor the health of managed servers and restart the 
server when appropriate 

Force the shutdown of a managed server that has failed to respond to a 
shutdown request 



In this section, you find out how to set up Node Manager and use it to per- 
form various tasks. 
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Node Manager, you must perform the following tasks: 

1. Set up the Node Manager hosts file. 

2. Configure SSL for Node Manager. 

3. Configure a control machine to use Node Manager. 

4. Configure startup arguments for managed servers. 

You can perform all these tasks from Administration Console. After these pre- 
requisite tasks have been performed, Node Manager is ready for use and is 
available from Administration Console. You'll then be able to start and stop 
managed servers and configure exactly how Node Manager operates. 



Setting up the Node Manager hosts file 

Node Manager will accept commands only from servers running on trusted 
hosts. You can identify a trusted host by an IP address, such as 
192 . 168 . 1 . 1, or by a domain name, such as www . mycompany .com. 

Only machines that have their IP address or domain name in the hosts file 
will be allowed to connect. By default, the hosts file is named nodemanager . 
hosts and is installed in the following directory: 

c:\bea\weblogic81\common\nodemanager\config 

To specify a different name and location for the trusted hosts file, you simply 
use a Node Manager command-line argument. For more information, see the 
upcoming "Configuring startup arguments for managed servers" section. 

The nodemanager . hosts file contains one line for each trusted host on 
which Administration Server runs. The nodemanager . hosts file provided 
with WebLogic contains the following: 



1 ocal host 
127.0.0.1 



The hosts file is an ordinary text file that can be edited with any text editor. 
Using this text editor, you can easily add or remove hosts. 

If you want to identify a trusted host by its host name, you must enable 
reverse DNS lookup. This option is specified when starting Node Manager by 
including the following command-line option: 



-Dwebl ogic.nodemanager.reverseDnsEnabled=true 



Chapter 4: Configuring and Administering WebLogic 



Without the command-line parameter, the default is to disable reverse DNS 
lookup. 

al production environment, Node Manager should not be on the 
same machine as Administration Server. Make sure that nodemanager. hosts 
contains only those machines that host Administration Server. Also make 
sure that your Node Manager machine is not accessible to the outside world 
through your firewall. Otherwise, it could be used by hackers to compromise 
your system. 

Configuring SSL for Node Manager 

Communication between Node Manager and Administration Server must be 
secure. Because of this, the Secure Socket Layer (SSL) protocol is used. This 
security is bidirectional, in that messages from both Node Manager and 
Administration Server are encrypted with SSL. 

To make use of SSL encryption, you must use a public key infrastructure, 
which includes a password-protected private key and an identity certificate. 
Node Manager uses the same certificate format and public key infrastructure 
that WebLogic Server uses. 

Before you can do much with Node Manager, you must obtain a key and cer- 
tificate files. These are usually obtained from a vendor such as Verisign. 
Obtaining SSL keys and certificates is covered in Chapter 18. 

For testing, WebLogic includes demonstration key and certificate files named 
demokey . pem and democert . pem, respectively. They enable you to set up 
and use SSL communication. After you install WebLogic, these files are avail- 
able in various folders on your system, as summarized in Table 4-2. 



Table 4-2 Directories for SSL Certificates 




Directory 


What It Does 


\samples\server\config\examples 


Contains the keys used for the 




exampl es domain 


\samples\server\config\petstore 


Contains the keys used for the pet 




store domain 


\ common \nodeman age r\ co nf i g 


Contains the keys for use with the 




installed Node Manager application 



(continued) 
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What It Does 



omain directory 



Contains the sample key and certifi- 
cate files that are copied to your 
own domains when you create your 
domains through Configuration 
Wizard 



It's a good idea to use the sample security files when you're testing and devel- 
oping your system. They enable you to get up and running quickly without 
purchasing real SSL certificates. 

Using these files, I will now show you how to configure SSL for Administration 
Server. Authority certificates are stored in a special location known as a key- 
store. You must specify the location of the path to the keystore by using the 
following startup argument: 

-Dwebl ogi c . securi ty . SSLtrustedCAKey Store 

You must make sure that Administration Server's startup script or service 
command-line specifies this argument. For example, the following startup 
command specifies the paths to these two files: 

Java -Xms200m -Xmx200m -classpath 
%CLASSPATH% -Dwebl ogi c . Name=myadmi n server 
-Dbea . home=c : \bea -D j a va . securi ty . pol i cy= 
c : \bea\webl ogi c81\ server \1 i b\webl ogi c . pol i cy 
-Dwebl ogi c . securi ty . SSL . trustedCAKeyStore = 
c : \bea\webl ogi c81\server\lib\ca certs 
webl ogi c . Server 

When calling Java from the command line as just shown, you can't use line 
breaks as part of the command line. In an actual script file, the preceding 
command would be represented as one long line. 



Configuring a control machine 
to use Node Manager 

Some configuration is required before you can use Node Manager. First, you 
must create a machine definition for each machine that runs a Node Manager 
process: 
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1. Log on to Administration Console. 
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the left side of the Administration Console screen, click the 
hines folder. 



The information on the right side of the screen changes to reflect the 
configuration area you selected. 

3. On the right side of the screen, click the Configure a new Machine link. 

4. Make sure that the General tab (of the Configuration tab) is displayed. 
Then, in the Name box, type a new name for your machine, as shown 
in Figure 4-5. 

Your machine name should be unique, and should make it easy for you 
to associate the computer with that name. 

5. Click the Create button. 

WebLogic creates your machine definition. 

6. Click the Node Manager tab. 

The screen shown in Figure 4-6 appears. 

7. Type the listen address and port that Node Manager uses for requests. 

Usually, you should accept the default values for the IP address and 
port. If you use a different IP address and port, you must provide this 
information to each node. 



Figure 4-5: 

Configuring 
a new 
machine. 
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Figure 4-6: 

Setting up 
an address 
and a port. 
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Connected to : 127.0.0.1 7001 



You are logged in as : admin 



Monitoring | Notes | 
General | Node M.m.Kjei | Servers 

Node Manager is a Java program provided with WebLogic Server that enables 
you to start, shut down, restart, and monitor the health of Managed Servers. 
Node Manager allows you to control Managed Servers from a remote machine, 
and is required if you wish to use the Administration Console to control 
Managed Servers. To utilize Node Manager capabilities for a Managed Server, 
Node Manager must run on the physical machine that hosts the Managed 
Server. This page allows you to define the Node Manager configuration for this 
machine. 



Listen Address: localhost ] 

The host name or IP address where Node Manager listens for 
connection requests. 
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8. Click the Apply button to save your changes. 

9. Click the Servers tab. 

A screen similar to the one in Figure 4-7 appears. 

10. Specify which of the domain's servers will work with Node Manager. 

To specify a particular server, click the check box next to that server's 
name. 



11. Click Apply to apply your changes. 



Configuring startup arguments far 
managed serOers 

The Administration Server SSL configuration applies to the domain as a whole. 
After configuring Administration Server, each Node Manager instance that you 
run in the domain must specify startup arguments that identify the location of 
the keystore, password, and certificate files to use for SSL communication. 

SSL is configured by providing command-line properties to Node Manager. 
Table 4-3 lists these command-line properties. 
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Figure 4-7: 

Specifying 
servers 
for Node 
Manager. 
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Table 4-3 Node Manager SSL Command-Line Properties 


Property 


What It Does 


-Dweblogic.nodemanager. key Fi 1 e 


Specifies the path to the key file, 
which could be encrypted. 


-Dwebl ogi c . nodemanager . 
keyPassword 


Specifies the password to use if the 
key file is encrypted. 




-Dwebl ogic. nodemanager. 
certi f i cateFi 1 e 


Specifies the path to the certificate 
file. 


-Dwebl ogic.security.SSL. 
trustedCAKey Store 


Specifies the path to the keystore 
that holds a private key. 


-Dwebl ogic. nodemanager. 
sslHostNameVerificationEnabled 


Controls Administration Server 
host name checks against the 
nodemanager.hosts file. This 
should be disabled only when 
you're using demonstration 
certificates. 
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For example, to start Node Manager using the SSL configuration provided 
with the sample SSL certificate and key, you would use the following lengthy 



java.exe -Xms32m -Xmx200m -classpath %CLASSPATH% 
-Dbea . home=c : \bea 
-Dwebl ogi c . nodemanager . key Fi 1 e= 
c : \bea\user_domai ns\mydomai n\ demo key . pern 
-Dwebl ogic.security.SSL. trustedCAKeyStore= 
c:\bea\weblogic81\server\lib\cacerts 
-Dwebl ogi c .nodemanager . certi f i cateFi 1 e= 
c : \bea\user_doma i ns\mydomai n\ demo cert . pern 
-Dja va . securi ty . pol i cy= 
c:\weblogic81\server\lib\weblogic.policy 

-Dwebl ogic.nodemanager.sslHostNameVerificationEnabled = false 
web 1 ogi c .nodemanager .NodeManager 

Although the preceding code looks like more than one line, you must enter it 
as a single command. 



Starting Made Manager 

Node Manager is a Java program and can be started by simply using the Java 
command. In a production environment, you should automate this process 
by specifying that Node Manager be started as either a Windows service or 
a UNIX daemon. 

In this section, you find out how to start Node Manager both from start 
scripts and as a Windows service. For more information about starting pro- 
grams as UNIX daemons, refer to Chapter 3. 



Starting Node Manager using start scripts 

WebLogic includes some sample start scripts that you can use to start Node 
Manager. These start scripts are installed in the following directory: 

c:\bea\weblogic81\server\bin 

The name of your start script is as follows. 

«>* startNodeManager.cmdfor Windows 
f" sta rt NodeManager . sh for UNIX 

Both scripts set the required Node Manager environment values and start the 
Node Manager process. 
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When the script is executed, the current directory is changed to the following: 

\weblogic81\common\nodemanager 



rectory will be used as a working directory for storing output and log 
files. If you want to specify a different working directory, edit the start script 
with a text editor and set the value of the N0DEMGR_H0ME variable to the 
directory that you would like to use. 

It's also necessary to edit the sample start script to ensure that Node 
Manager startup arguments are set to the correct listen address and port 
number for your Node Manager process. 

Starting with a start script is useful in a development environment, where 
you may need to stop and start Node Manager frequently. 



Starting Node Manager as a 
Windows service 

The c : \bea\webl ogi c81\ server\bi n directory also contains scripts to 
install and uninstall Node Manager as a Windows service. These scripts are 
named i nstal 1 NodeMgrSvc . cmd and uni nstal 1 NodeMgrSvc . cmd. You can 
invoke either script from the command line. 

In a production environment, it's a good idea to run Node Manager as a ser- 
vice. This ensures that no one has to be logged on to the server for Node 
Manager to be running. 

When you run i nstal 1 NodeMgrSvc . cmd, it creates a default Windows ser- 
vice for Node Manager named NodeManager_l ocal host_5555. You may 
want to edit i nstal 1 NodeMgrSvc . cmd before running the script to change 
the service name or to use nondefault environment variables or startup argu- 
ments. If you edit i nstal 1 NodeMgrSvc . cmd to change the listen port or host 
name, make the same change to uninstallNodeMgrSvc.cmd so that it 
removes the correct service name. 



Setting Node Manager environment 
Variables 

You can set many of the options of Node Manager by using environmental 
variables. You are not required to use all the features of Node Manager. By 
default, Node Manager performs as follows: 
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W The automatic restarting of managed servers is enabled. 
The automatic shutdown of managed servers is disabled. 



6 Manager monitors the managed servers that it has started. 
In this section, you see how to change these settings. 

Environmental variables are operating system variables that hold configura- 
tion information. Node Manager uses environmental variables to specify con- 
figuration settings. These are already set up for you when you run the startup 
scripts described previously. If you will be modifying the startup scripts, 
however, you must know the meanings of these environmental variables. A 
complete list of these variables is given in Table 4-4. 



Table 4-4 



Node Manager Environmental Variables 



Variable 


What It Does 






CLASSPATH 


Specifies the location of JAR files. 




JAVAJOME 


Specifies the JVM that you will use for Node Manager. This 
should be set to the directory that Java is installed to. 


PATH 


The PATH environment variable should include th 


e 



WebLogic Server bin directory as well as the path to your 
Java executable. This specifies the path to executables that 
must run. 



WL HOME 



Specifies the directory that WebLogic was installed into (for 
example, c : \bea\webl ogi c81) 



You can also set several Java properties when starting Node Manager. 
The following command shows the format for starting Node Manager using 
properties: 

Java [java_property=val ue ...] -D[nodemanager_property=val ue~\ 

-D[server_property=va 1 ue~\ 

web 1 ogi c . nodemanager .NodeManager 

A nodemanager_property begins with the prefix webl ogi c .property and 
directly affects the behavior of the Node Manager process. Table 4-5 summa- 
rizes these properties. 




If you specify your own options for Java, always specify a minimum heap size 
of 32MB (- Xms32m) to avoid running out of memory. If you're using the 
scripts provided with WebLogic, this value is set automatically. 
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Table 4-5 


Node Manager Properties 




Default 


What It Does 


web Togi c . 

Li stenAddress 


localhost 


Specifies the address where 
Node Manager listens for 
connection requests. 


webl ogi c . 
Li stenPort 


5555 


Specifies the TCP port 
number where Node 






Manager listens for connec- 
tion requests. 



webl ogi c . 
nodemanager . 
certi f i cateFi 1 e 



. /conf i g/ 
democert . 
pem 



Specifies the path to the 
certificate file used for 
SSL authentication. 



webl ogi c . 
nodemanager . 
javaHome 



none 



Specifies the Java home 
directory that Node Manager 
uses to start Managed 
Servers. 



webl ogi c . 
nodemanager . 
key Fi 1 e 


. /conf i g/ 
demokey . 
pem 


Specifies the path to the 
private key file to use for SSL 
communication with 








Administration Server. 


webl ogi c . 
nodemanager . 
keyPassword 


password 


Specifies the password used 
to access the encrypted 
private key in the key file. 



webl ogi c . 
nodemanager . 
nativeVersionEnabled 



true 



For UNIX systems other than 
Solaris or HP-UX, set this 
property to false to run Node 
Manager in non-native mode. 



webl ogi c . 
nodemanager . 
reverseDnsEnabl ed 



false 



Specifies whether entries in 
the trusted hosts file can 
contain DNS names (instead 
of IP addresses). 



webl ogi c . 
nodemanager . 
savedLogsDi rectory 



./NodeManagerLogs 



Specifies the path in which 
Node Manager stores log 
files. Node Manager 
creates a subdirectory in 

savedLogsDi rectory 
named NodeManagerLogs. 
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web rogi c . 
nodetnanager . 
ssl HostName 
Veri f i cati on 
Enabl ed 



webl ogi c . 
nodemanager . 
startTempl ate 



webl ogi c . 
nodemanager . 



Default 



What It Does 



false 



Specifies whether or not 
Node Manager performs 
host name verification. 



. /nodemanager . sh 



For UNIX systems, specifies 
the path of a script file used 
to start managed servers. 



. /nodemanager . 
hosts 



Specifies the path to the 
trusted hosts file that Node 



trustedHosts 


Manager uses. See the 
"Setting up the Node 
Manager hosts file" section. 


webl ogi c . 
nodemanager . 
webl ogi cHome 


n/a 




Specifies the root directory 
of the WebLogic Server 
installation. This is used as 
the default value of 

-Dwebl ogi c . 






RootDi rectory 
that do not have a 
root directory. 


for servers 
configured 



Monitoring the Server 

Monitoring is an important part of WebLogic administration. Monitoring 
allows you to quickly see an overview of how different parts of WebLogic are 
performing. WebLogic allows you to monitor the following areas: 

CORBA connection pools 
W EJB 
f HTTP 
V JDBC 
^ JMS 
^ JNDI 



v 0 JTA subsystem 
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oring activity takes place through Administration Console. The mon- 
itoring functions of Administration Console are not isolated to one specific 
area. Rather, these functions are placed in the same area as the system that 
they're monitoring. 

In general, to find the monitoring page for a specific service in WebLogic, 
follow these steps: 

1. Log on to Administration Console. 

2. In the Services folder (on the left side of the screen), click the folder 
representing the service you want to monitor. 

The information at the right side of the console changes to reflect the 
service you selected. 

3. On the right side of the screen, click the Monitoring tab. 

The monitoring page shown in Figure 4-8 appears. 



Figure 4-8: 

Beginning 
the 

monitoring 
process. 
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mydomain> JDBC Connection Pools> SchoolPool 

Connected to : 127.0.0.1:7001 | You are logged in as : admin | 
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The monitoring page shows you how many connections are active, how many 
threads are waiting on a connection, and how many connections are unavail- 
~ here, you can monitor your connection. 
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In this part . . . 



MM/ebLogic Server can make use of many different com- 
▼ ▼ ponents. In this part, you find out about these com- 
ponents and how they interact. You begin by constructing a 
web application. This application becomes the foundation 
upon which you build many of your other components. 

Next, you're introduced to EJBs — Enterprise JavaBeans. 
EJBs allow you to create models that perform specific 
tasks. You find out about two types of EJBs — stateful and 
stateless session beans — as well as BMP (bean-managed 
persistence) and CMP (container-managed persistence) 
entity beans. 

Then you create the one component that ties together all 
the other components: an enterprise application. The 
enterprise application can hold a web application and the 
EJBs used by that web application. In this way, you can 
package your application as one complete application. 
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In This Chapter 

Finding out the differences between web and application servers 
Setting up your first web application 
Understanding what's in a web application 
Using JSP, servlets, and JSTL 

•••••••••••••••••••••••••••••••••••••••••••••••a* 

JM web server can send a wide range of files to a client, on request. These 
v \ files are the HTML, JSP, servlet, and other files needed to display your 
web site. These files, taken collectively, are referred to as a web application. 
Creating a web application is the topic of this chapter. 

Sen/er Basics 

The difference between a web server and an application server can be con- 
fusing. As web and application servers continue to evolve, considerable over- 
lap is created between the roles of these two types of software. 

A web server is a program that sends web pages to a browser so that they 
can be displayed to users. For example, when you use your browser to visit a 
search engine, the browser requests the web page containing the search form. 
The server provides the form to your browser, which in turn displays the form 
for you to use. When you fill out the form, your browser sends your informa- 
tion to the web server. In short, the web server's primary job is interacting 
with the client software, such as your web browser. 

Following are examples of programs commonly thought of as web servers: 

i>* Apache: One of the oldest web servers and the leading one as measured 
by its installed base. Apache is open source and freely available. 

Microsoft Internet Information Server (IIS): Microsoft's web server, 
commonly used to run active server pages (ASP). IIS is the second 
largest web server, as measured by its installed base. 
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Tomcat: A freely available open-source web server. Tomcat can be used 
either as a stand-alone server or with another web server that doesn't 
ort JSP on its own. 



application server is a program whose primary purpose is to process data 
entered by the user. The application server does this by managing connec- 
tions to the database. The user doesn't see the application server directly 
The web server accesses the application server, and the user sees only the 
results of the application server's work through the web server. An applica- 
tion server can't be used alone to create an application, so most application 
servers, such as WebLogic and WebSphere, include their own web server as 
well. This allows you to deliver a complete application with both the web and 
application servers. 

The following programs are commonly thought of as application servers, 
though some are capable of functioning also as web servers: 



V WebLogic. A commercial application and web server developed by BEA 
Systems. 

W WebSphere. An application and web server developed and marketed by 
IBM and usually used with IBM's Visual Age products. 

V JBoss. An open-source application server. JBoss does not have the 
market share of WebLogic or WebSphere, but it's gaining in popularity. 



Setting Up a Web Application 

WebLogic is a great tool for setting up web applications. And in this section, 
you discover how to use WebLogic to do just that. The following steps are 
involved in setting up a web application: 



1. Create your server. You create a server instance in WebLogic's 
Administration Console. 

2. Create your web application. You create the web application in Admini- 
stration Console. This will be a simple web application that doesn't yet 
have any content. 

3. Test your web application. After you create your web application, you 
start your server and make sure that you set up the basic web applica- 
tion properly. 

4. Program your web application. Now that your web application is work- 
ing correctly, you can add some content. Programming your web appli- 
cation is a lengthy process that uses several technologies. This is by far 
the most time-consuming step. The amount of time that it takes is deter- 
mined by the complexity of your web application. 
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Package your web application. You can optionally decide to package 
your web application into a WAR file — a single module file that contains 
ly all your web application. (Only external resources such as data- 
s are not included.) This can make it very easy to distribute your 
web application. 

6. Deploy your web application. After you package your web application, 
you can deploy it to any number of servers. After your web application 
is deployed, it's ready to be used. 

Creating, testing, packaging, and deploying your web application take little 
time compared to programming your web application. At the end of the chap- 
ter, I present an overview of the technologies available for programming your 
web application. More detailed information on individual technologies that 
you can use to build your web application can be found in other chapters. 

The three steps of creating, testing, and deploying your server could be con- 
sidered initial setup tasks. However, you create your server only once, but 
you test and deploy it repeatedly as you change your web application. 



Creating your server 

To run a web application, you need a server. One server can host multiple web 
applications. The easiest way to create a server is to use Domain Configuration 
Wizard. In Chapter 2, 1 go into the details of creating a server using Configur- 
ation Wizard, so refer to that chapter for more information. 



Creating your Web application 

In this section, I show you how to create a web application. A web application 
can come in one of two forms. In this section, you create an exploded web appli- 
cation, which is made up of actual directories on your server computer. The 
other form of web application is a web archive (WAR) file, which contains the 
directory structure of an exploded web application. 

Usually, you begin with an exploded web application, because it's easier to 
work with the files in a regular directory structure. Then you package your 
exploded web application into a WAR file. 

Follow these steps to create a web application: 

1. Make sure that WebLogic is not running. 

If you started WebLogic from the Start menu, simply close WebLogic's 
window. If you started WebLogic as a service, stop the service. 
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2. Create your application directory. 

Choose a name for your web application and create a directory of the 
e name in your domain's appl i cations directory. For example, if 
wanted to create an application named myapp, you would create a 
directory named 

c : \bea \user_projects\mydomai n\appl i cati ons\myapp 



3. Create an index file named index.html. 

Create an index file that will be displayed when the user visits your web 
site. Listing 5-1 shows a sample index file. 

4. Create your W E B I N F directory. 

The WEB - 1 N F directory holds configuration files needed by your web 
application. You should create aWEB-INF directory within the directory 
you created in Step 2. If your web application were named myapp, for 
example, your WEB - 1 N F directory would be named 

c : \bea \user_projects\mydomai n\appl i cati ons\myapp\WEB- INF 

5. Create a web application descriptor named web.xml and save it in the 
WEB INF directory. 

Listing 5-2 shows a sample web.xml file. 



Listing 5-1: Sample index.html File 



<html> 
<head> 

<title>Welcome</title> 

</head> 

<body> 

<hl>Welcome</hl> 

</body> 

</html> 



Listing 5-2: Sample web.xml File 

<?xml version = "l .0" encodi ng="UTF-8" ?> 

<!D0CTYPE web-app PUBLIC 

"-//Sun Microsystems, Inc. //DTD Web Application 2.3//EN" 
" http : // Java. sun. com/dtd/web-app_2_3 . dtd" > 

<web-app> 

<displ ay-name >Example Appl i cati on</di splay-na me > 
</web-app> 

Now that you've created your web application, you're ready to test it. 
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.our web application, you need to first start your server. You can 
eb server in several ways; see Chapter 3 for the details. 



If you decided to have your web server start as a Windows service, the 
server will start automatically when you reboot (and on all subsequent 
reboots). If you want to start your server as a Windows service without 
rebooting, open the Windows Control Panel, double-click Administrative 
Tools, and then double-click the Services icon. Your new server begins with 
the prefix beasvc followed by the domain and server name that you chose in 
Chapter 2. 

If you didn't set up your server as a Windows service, you should start 
your server using its icon. Choose StartOBEA WebLogic Platform 8.10 
User ProjectsO(>bur Domain /Vame)C>Start Server. (Your Domain Name) is 
the name of the domain that you created in Chapter 2. The screen shown in 
Figure 5-1 appears. 

Now, to verify that your web application is running, open your favorite 
browser and type the following in the URL box: 



Figure 5-1: 

Your 
new web 
application. 
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This URL assumes that you used the default port when you created your 
server. If you used a different number for your port (see Chapter 2), replace 
that number. 



pBodte 

Programming your Web application 



Assuming that you followed the steps outlined earlier in the chapter (and 
that you named the domain for your server mydomai n), the root directory for 
this web application is 

C : \bea\user_projects\mydomai n\appl i cati ons\myapp 

You may want to simply use this web application on your single WebLogic 
Server. However, now is the time that you would normally begin program- 
ming your web application. You can use many different technologies to do 
this. Later in this chapter, I introduce you to some of them. Other chapters 
are dedicated to showing you how to use WebLogic and J2EE technologies to 
construct your web application. 



Packaging your Web application 

At this point, you haven't created much of a web application. Other chapters 
show you how to create more advanced web applications. After you've cre- 
ated a more advanced web application, you'll likely want to package it as a 
web archive (WAR) file. Doing so means you'll be able to rapidly deploy your 
application on another server by simply copying the WAR file to the new 
server and using Administration Console to deploy the file. 




Packaging is not a step that you do only once. As your web application 
grows, you have to repackage it each time you need an up-to-date WAR file. 



If you'll be creating an enterprise application, you need to package your web 
application as a WAR file. Enterprise applications are discussed in Chapter 8. 

To create a WAR file from DefaultWebApp, issue the following command from 
a command prompt: 

jar cvf MyWebApp.war -C web-app-di r * .* 

replacing web-app-di r with the root directory of your web application. For 
example, you could use the following to create a WAR file for the sample 
application developed in this chapter: 

jar cvf MyWebApp.war -C 

C : \bea\user_projects\mydomai n\appl ications\Default 
WebApp *.* 
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If you haven't added the JDK bi n directory as part of your system path, you 
myst use the full path name of the jar command, as shown here: 

\jdkl31_03\bi n\jar cvf MyWebApp .war -C 

C : \bea\user_projects\mydomai n\appl ications\Default 
WebApp *.* 



Deploying your Web application 

Now that you've packaged your web application, you can deploy it to any 
WebLogic Server that you want. You can also make it part of an enterprise 
application, as discussed in Chapter 8. WebLogic includes a program called 
Administration Console that can help you with most of the work necessary 
to deploy your web application. (For more on Administration Console, see 
Chapter 4.) 

After you create your web application, you may want to change some of its 
options. Fortunately, these settings are not set in stone. You can change them 
by configuring your web application. The best way to find out how to config- 
ure your server is to just jump right in and do it: 

1. Log on to Administration Console. 

If you need a refresher on how to do this, refer to Chapter 4. Here, how- 
ever, you need to use your administrative username and password to 
actually log on. 

2. In the left pane, click the Deployments folder, and then click the Web 
Application Modules folder. 

The right pane looks similar to Figure 5-2. 

3. In the right pane, click the Deploy a new Application link. 

4. Click the upload your filefe) link. 

This link is in the right pane, in the "Step 1" section. The screen shown 
in Figure 5-3 appears. 

5. Locate and open the WAR file that you want to add. 

Click the Browse button, locate your WAR file, and then click Open. 

6. Upload the WAR file. 

WebLogic reads the WAR file and displays a directory at the bottom of 
the right pane, as shown in Figure 5-4. 
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7. In the directory tree, click the radio button link to the left of the JAR 
file name. 

You may have to scroll to see the radio button and WAR file name. 

8. Type a name for your web application. 
The name can contain letters and numbers. 

9. Click Deploy. 

Now that you've seen how to create and deploy a web application, it's time to 
look at some of the technologies that you can include in a web application. 



Directory Structure for \lour 
Web Application 

Earlier in this chapter (in the section "Creating your server"), you created a 
directory to hold your web application. This is only the root-level directory 
for your application. You should create other directories — in fact, an entire 
directory structure — to help organize the information in your application. 
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As an administrator, you must be aware of the directory structure of your 
web application. Doing so will help you make your application more efficient 
omical on space, as well as more logical for you and others who 
k with your application. Table 5-1 shows some of the important 
directories and files contained in your web application. 



Table 5-1 WEB-INF Subdirectories and Files 



Directory and File 


What It Is 








WEB-INF/web.xml 


The main web application deployment 
configuration file. This file contains many 
configuration settings and has a standard 
format, so it can be used by many different web 
servers. 


WEB- INF/webl ogi c . xml 


This file is similarto web . xml excepl 
contains settings specific to WebLogi 


[it 
c. 


WEB-INF/classes 


Contains server-side class files, such 
servlets. 


as 


WEB- INF/1 ib 


Contains JAR files used by the web a 
JAR files contain Java classes that w 


□plication, 
ill be used 




by your web application. 




The WEB-INF directory is a private directory in your domain's root directory. 
Private directories are not accessible to users who browse your web site. All 
configuration information for your web application is stored in this directory. 



Later, when you want to deploy your web application, you copy this direc- 
tory structure or archive it to a web archive (WAR) file. 

Now that you have an overview of the technologies that make up a web appli- 
cation, it's time to see how to use some of them. 



The Files in a Web Application 

Now you have a generic web application that's like any web application cre- 
ated with WebLogic. In this section, you make your web application perform 
a task by adding different types of custom files to it. Following are some of 
these custom files: 

f JSP (JavaServer Pages). Similar to HTML files in that they contain 
HTML formatting information that defines how to display the page. 
However, JSP can contain embedded Java that further defines the 
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appearance of a page, so JSP is dynamic. For more information about 
how to program JSP, see Making Use of JSP by Madhushree Ganguli (pub- 
d by Wiley Publishing, Inc.). 



(JSP Standard Tag Library). Another way of programming JSP. 
Instead of using Java commands, however, you use special tags, like 
HTML. The result is a more consistent JSP file. For more on program- 
ming JSTL, see my book on JSTL, JSP Standard Tag Library Kick Start 
(published by Sams). 

v 0 Servlet. A Java program that produces HTML output. Most 
functions of the servlet have been replaced by JSP and JSTL. For 
more information about how to program servlets, check out Java Servlet 
Programming Bible by Suresh Rajagopalan (Editor), Ramesh Rajamani, 
Ramesh Krishnaswamy, and Sridhar Vijendran (published by Wiley 
Publishing, Inc.). 



Usinq JSP 

One common way to create web applications is to use Java Server Pages 
(JSP). With JSP, you can generate web pages that pull their content from a 
variety of sources, such as user input or a database. Unlike HTML pages, 
which remain the same from view to view (they're static), JSPs can change 
their content (they're dynamic). JSPs usually form the front line of your web 
application because they're the level that the user directly interacts with. 

Finding a home for JSPs 

When you create JSP files, you store them in the root directory of your web 
application, but they're not limited to that location. You can also create subdi- 
rectories and place JSP files there as well. You determined the location of your 
web application's root directory when you created your web application. 

You can also create additional directories under the root directory. For exam- 
ple, you might want to create a directory named images to hold all graphic 
files used with your web application. 



Creating a JSP (ite 

JSP files are ordinary text files, so you can create a JSP file with any text file 
editor. 



You can create JSP files also with HTML editing tools such as FrontPage or 
Dreamweaver. Although HTML editors such as these are of little help writing 
the Java source code part of a JSP, they can help you to create the HTML that 
provides the look and feel of your JSP. 
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JSPs are a blend of HTML and Java code. If you know Java, it won't take you 
long to figure out how to create JSPs. This book doesn't attempt to teach you 
d out more about JSP, refer to Making Use of JSP by Madhushree 
published by Wiley Publishing, Inc.). 



Figure 5-5 shows an example of a web page created using JSP. This page dis- 
plays a form that allows the user to enter an ID and a password. The program 
then displays that same information. This simple example shows the dynamic 
nature of JSP, in that the JSP can integrate the data that you enter with the 
HTML that it displays. 



£1 Form Example - Microsoft Internet Explorer QsJu 
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web page. 
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The source code for this page is shown in Listing 5-3. The JSP code is not 
very long, but it runs quite handily on WebLogic. 



Listing 5-3: JSP to Prompt the User for an ID and a Password 

<html> 
<head> 

<title>Form Exampl e</ti tl e> 
</head> 
<body> 
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i f ( request . getMethod( ). equal s IgnoreCase( "post" ) ) 

%> 

,d : <%= request . get Parameter ( "uid" )%Xbr/> 
cd:<%= request. getParameter ( "pwd" )%><br/> 



<%} 

%> 

<table border=0> 

<f orm method="post"> 
<tr><td>User Id</td> 

<td><input type="text" name=" ui d" ></td> 
</tr> 

<tr><td>Password</td> 

<td><input type="text" name=" pwd" X/td> 
</tr> 

<tr><td col span = "2"Xi nput type=" submi t" /> 
</tdX/tr> 
</f orm> 
</table> 
</body> 
</html> 



The JSP is a mix of HTML and Java code. When Java code appears in JSP, 
the code is enclosed by <% and %>. This is true for both large blocks of code, 
spanning several lines, or a small block containing a single statement (as in 

The following steps summarize how the JSP in Listing 5-3 executes: 

1. The example page is loaded into the browser. No POST is detected, so 
the form is displayed. 

2. The user enters data. 

3. The form POSTs the entered data back to itself. 

4. The example page begins again. A POST is detected, so the POSTed vari- 
ables are displayed. 



You may be wondering what I mean by POSTing data. HTTP (the underlying 
protocol of the Web) has three basic types of requests: POST, GET, and HEAD. 
HEAD simply verifies that a page still exists. Search engines typically use the 
HEAD request to purge their lists of dead links. The two request types that 
you need to understand are GET and POST. 



The GET request is the most common request type. When a browser requests a 
web page, it uses a GET request. When you type a URL in a browser or follow a 
hyperlink, you're performing a GET request. Step 1 of this JSP page checks to 
see whether a POST request is being performed, by using this line: 

if ( request. getMethodO. equal sIgnoreCase( "post")) 
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If this is the first request for the page, the request method is a GET request, 
not a POST request. Thus, the JSP simply displays the form to request user 
on. 



When Step 3 is performed, however, the page is retrieved using a POST 
request. The POST request is similar to a GET request. In both the POST and 
GET requests, you request a URL and get a page back. The main difference is 
that the POST request allows you to supply additional information with the 
request. In Listing 5-3, the extra information is the data that the user entered. 
When you reach Step 3, the JSP detects that a POST request is in progress and 
displays the results of the POST request rather than the form. 



Step 4 now begins. The user may enter information and begin the process 
again. 



5" 



You can save time by designing a JSP to POST back to itself. Otherwise, you 
need two JSPs: one to display the form and a second to process the data 
returned by the form. POSTing to the JSP that created the form saves having 
to have two JSPs for each form. 

JSP pages are converted to Java source files. These source files are then com- 
piled to servlets and presented to the user as the application runs. 



A quick took at sevviets 



A servlet is nothing more than a Java class constructed so that it can output 
to a web server. In the old days (before JSPs), you could create interactive 
Java web pages only by using servlets. 

A JSP file is actually a servlet. The code in a JSP file is first translated to a 
Java file. This Java file contains a servlet. When you create the servlet your- 
self, the translation step is eliminated, resulting in faster execution time. 



Listing 5-4 shows a simple "Hello World" servlet. 



Listing 5-4: Servlet to Display "Hello World" 

import j avax . servl et . * ; 
import java.io.*; 

public class Exampl eServl et extends Generi cServl et 
( 

public void service(ServletRequest request, Servl etResponse 
response ) 

{ 

response. setContentl_ength(helloString.length()); 
response. setContentType("text/pl a in"); 
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PrintStream rs = new 

Pr intStream( response. getOutputStreamO) 
rs . pri nt ( " Hel 1 o , worl d\r\n" ) ; 



catch (IOException e) 
{ 

// handle any errors 
) 

) 

) 



If you're familiar with Java, you might notice in Listing 5-4 that a servlet is 
simply a regular Java program. The service method fulfills the same pur- 
pose as ma i n in a regular Java program. 

The servlet communicates by using the Servl etRequest parameter 
that's passed in. To send data back to the web browser, you use the 
Servl etResponse object, which is passed to the servi ce method. 
For more information on servlets, you might want to read Java Servlet 
Programming by Jason Hunter and William Crawford (published by O'Reilly 
& Associates). 



Uslnq JSTL 

One of the main disadvantages of both JSP and servlets is that they mix regu- 
lar Java program code and HTML-type tags, which display the page layout. 
JSP Standard Tag Library (JSTL), however, eliminates this difference by 
requiring the use of tags, rather than Java code. Because of this, Java pro- 
grammers find JSTL not as familiar as JSP. In many ways, JSTL is a new web 
programming language separate from JSP. 

Instaitinq JSTL 

To use JSTL, you must have a JSP 1.2 (or higher) server installed, such as 
WebLogic. (Isn't it handy that you just happen to have such a server?) 
WebLogic doesn't include JSTL support by default; it must be added. You 
can obtain JSTL from the following URL: 

http :// Java. sun. com /products/ jsp/jstl / 

From here, you can download and discover more about JSTL. 

To use JSTL, you must unzip the distribution files and install them in the cor- 
rect locations in WebLogic. Follow these three steps: 
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1. Copy the JSTL JAR files to WebLogic's 1 1 b directory. 

If you're using Windows, the likely location of your 1 i b directory is 

- 1 N F \ 1 i b. A number of JAR files are included with the JSTL release; 
each of these files to the WebLogic 1 i b directory. 

2. Copy the JSTL TLD files to WebLogic's W E B I N F directory. 

The WEB - 1 N F directory is probably at this location: \WEB- INF. If you 
look at the JSTL distribution files, you should notice eight files with the 
.tld extension. Copy all eight files to your WEB - INF directory. 

3. Modify the web.xml file to include the TLD files. 

JSTL is made up of eight tag libraries. Add an entry for each library by 
adding < t a g 1 i b > directives inside the main <we b - a p p> directive. The 
entries you should add are shown in Listing 5-5. 



Listing 5-5: web.xml Entries Used for JSTL 



<taglib> 

<tagl i b- uri >http : // Java. sun. com/jstl /fmt</tagl i b- uri > 
<taglib-location>/WEB-INF/fmt.tld</taglib-location> 
</tagl ib> 

<taglib> 

<tagl ib-uri>http:// Java. sun. com/jstl /fmt- rt</tagl i b-uri > 
<tagl ib-1 oca tion>/WEB- IN F/fmt-rt.tl d</tagl ib- location) 
</tagl ib> 

<taglib> 

<t agli b-uri >http : // Java. sun. com/jstl/co re </tagli b-uri > 
<tagl ib-1 oca tion>/WEB- IN F/c.tld</tagl ib-1 ocation> 
</tagl ib> 

<taglib> 

<taglib-uri>http:// Java. sun. com/jstl/core-rt</taglib-uri> 
<tagl ib-1 ocation>/WEB-INF/c-rt .tl d</tagl i b-1 ocati on> 
</tagl ib> 

<taglib> 

<taglib-uri>http:// Java. sun. com/jstl /sql</tagl i b-uri > 
<tagl ib-1 ocati on>/WEB-INF/sql .tl d</tagl ib-1 ocati on> 
</tagl ib> 

<taglib> 

<taglib-uri>http:// Java. sun. com/jstl/sql-rt</taglib-uri> 
<tagl ib-1 ocati on > /WEB- IN F/sql -rt . tld</tagl ib-1 ocati on> 
</tagl ib> 



<tagl ib> 
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<t agl i b-uri >http : // Java. sun. com/jstl/x</taglib-uri> 
<tagl ib-location>/WEB-INF/x.tld</tagl ib-1 ocation> 
glib> 



51ib> 

<taglib-uri>http:// Java. sun. com/jstl/x-rt</taglib-uri> 
<tagl ib-1 ocation>/WEB-INF/x-rt .tl d</tagl i b-1 ocati on> 
</tagl ib> 



You're now ready to test your installation of JSTL. To do so, create a JSP file 
that uses JSTL. I will show you how to do this in the next section. 




If JSTL is not installed correctly and you try to view a JSTL page, you proba- 
bly won't see an error message. If JSTL is not interpreting your tags, they're 
passed through directly to the web browser. The web browser interprets 
these tags as unknown HTML tags, which most browsers simply ignore. 



A JSTL example 

JSTL code is stored in a JSP file. Because of this, you can easily mix JSTL code 
with both HTML and Java code, as shown in Listing 5-6, a simple JSTL exam- 
ple that counts to ten. 



Listing 5-6: Count to Ten Using JSTL 



<7o@ taglib uri =" http : //j ava . sun . com/ j stl /core" prefix="c" %> 
<html> 
<head> 

<title>If with Body</title> 
</head> 



<body> 



<c:if 
<c:i 
<br 


test=" $ { pageContext . request . method= : 
f test="${param.guess=='Java' )">You 

/> 


='P0ST' ["> 

guessed it! 


<br 


/> 






<br 
</c: 


/> 
if> 




<c:i 

<br 


f test="${param.guess!='Java' )">You 

/> 


are wrong 


<br 


/> 




<br 
</c: 


/> 
if> 





(continued) 
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orm method="post">Guess what computer language 
I am thinking of? 
<input type="text" name="guess" /> 

<input type="submit" value="Try!" /> 

<br /> 
</f orm> 
</body> 
</html> 

As you can see from Listing 5-6, there's no Java code on the page. Tag pro- 
gramming determines whether you guessed the correct word. A good exam- 
ple of tag programming is the method JSTL uses for an i f statement. The 
body of the i f statement is enclosed in <c : i f > and </c : i f > tags. The 
expression that the <c : i f > tag evaluates is provided by the va r attribute. 

Complete coverage of JSTL is beyond the scope of this book. For more infor- 
mation on JSTL, you might want to check out a book I wrote called JSP 
Standard Tag Library Kick Start (published by Sams). 
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In This Chapter 

Creating a stateless session bean 

Compiling, deploying, and testing your stateless session bean 

Adding state to a session bean 

Introducing entity beans and message-driven beans 



Enterprise JavaBeans, or EJBs, are individual units that you break your 
web application into and host using WebLogic Server. In this chapter, 
you create (and install) an EJB. These individual units represent functional 
areas of your web application, making your web application easy to maintain 
and increasing the likelihood of reusing the code. 

Creating EJBs, however, is only half of the story. Your EJBs must ultimately be 
used somewhere. In this chapter, you also find out how to use these EJBs in 
web applications that you've created with WebLogic. 

Several types of EJBs are available: 

Stateful session beans. An EJB that holds information from one invoca- 
tion to the next. Holding this information requires overhead, so stateful 
session beans should be used sparingly. 

Stateless session beans. An EJB that doesn't hold any information from 
one invocation to the next. This is the most commonly used EJB. 

Entity beans. A bean that represents some form of persistent data. An 
entity bean usually corresponds to one record of data. 

Message beans. An EJB that receives JMS messages. 
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In this chapter, I focus on session beans, presenting an example of both a 
stateful and stateless EJB. These are the two most basic types of EJBs sup- 

WebLogic. Entity beans are described in Chapter 7. Message beans 
uced here and discussed in Chapter 15. 



Creating Stateless Session Beans 

In the world of Enterprise JavaBeans, a stateless session bean simply means 
that the bean doesn't remember anything from one invocation to the next. 
This is useful because it takes some overhead to maintain this memory. You 
should use stateless session beans whenever possible. 

To create a stateless session bean, you must include five components: 

f Remote interface. The client class uses this interface to call your EJB. 

f Home interface. The client program uses this interface to create 
instances of the EJB. 

\S Bean class. The bean class holds the functionality of the bean. Most of 
your code will be placed in this class. 

V Deployment descriptor. The deployment descriptor is an XML file that 
contains the names of all the classes that make up your EJB. 

\S Client class. The client class is not part of the EJB. This is a class that 
calls the EJB. 

In this section, you find out what you must do to create each of these 
components. 



Creating the remote interface 

The process of creating a bean begins with the creation of a remote interface. 
Your remote interface must extend (using the Java keyword extends) the 
javax.ejb.EJBObject interface and define the methods that you want to 
make available with your EJB. The client uses the remote interface to access 
your EJB. The remote interface is only a template to specify how to access 
the bean class. You will have only method templates — no actual code. 

Your remote interface is implemented as a Java interface. A Java interface 
explains something that can be accomplished but never explains how to 
accomplish it. An interface does not contain program logic. It contains only 
method headers that list the methods available to any class that implements 
the interface. The remote interface for your stateless session bean is shown 
in Listing 6-1. 
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Listing 6-1 : Remote Interface for Your Stateless EJB 

1 e . j a v a 
com . dummi es . ejb ; 

import javax.ejb.*; 
import Java . rmi .*; 

public interface Sample extends EJBObject 
{ 

public String sampl eMethod( i nt n) 
throws RemoteExcepti on ; 

) 

I created a class named Sampl e that contains a single method named 

sampl eMethod. Although this EJB has only one method, you can add as many 

methods as needed to create your EJB. 



Creating the home interface 

After you create the remote interface, the next step is to create a home inter- 
face. The home interface is a Java class that extends the EJ BHome class. It's 
called a home interface because it's used by the client to instantiate 
instances of the EJB. 

The home interface defines the creation and removal of session beans. 
Fortunately, you don't need to write all the methods of the parent EJ BHome 
interface. You need to write only a c reate method that returns the type of 
remote interface. 

The home interface is shown in Listing 6-2. For stateless session beans, your 
home interface will always be this simple. 

Listing 6-2: Home Interface for Your Stateless EJB 

// Sampl eHome.java 
package com . dummi es . ejb ; 

import javax.ejb.*; 
import java . rmi .*; 

public interface SampleHome extends EJBHome 
{ 

public Sample createO 

throws RemoteExcepti on, Create Except ion; 




} 
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Creating the bean class 



point in your stateless session bean creation, you've created only 
faces. In this section, you create the bean class, where all the real 
work takes place. The bean class is a regular Java class that implements the 
SessionBean class. Listing 6-3 shows the bean class for your bean. 



Listing 6-3: Class for Your Stateless EJB 

// Sampl eBean . Java 
package com . dummi es . ejb ; 

import javax.ejb.*; 
import j ava . rmi . * ; 
import j avax . swi ng . * ; 

public class SampleBean implements SessionBean 
( 

private Sessi onContext stx; 

//Required methods, not used by this type of bean 
public void ejbCreate( ) I ) 
public void ejbRemove( ) { ) 
public void ejbActi vate( ) I ) 
public void ej bPassi vate( ) { ) 

// setter for the Sessi onContext 

public void setSessi onContext ( Sessi onContext ctx) 

( 

ctx = this. stx; 

) 



// the sample method 



public String sampl eMethod( i nt num) 
throws RemoteExcepti on 

{ 

swi tch ( num) 



case 1 
case 2 
case 
case 
case 
case 
case 7 
case 8 
case 



9 : 



return 
return 
return 
return 
return 
return 
return 
return 
return 



"One" ; 
"Two" ; 
"Three" 
" Four" ; 
" Five" ; 
"Six"; 
"Seven" 
"Eight" 
"Nine"; 
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defaul t : return "Some Number' 
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The bean class is more complex than the interfaces you created 
previously in the chapter. The setSessi onContext method receives 
javax.ejb.SessionContext, which you need for stateful beans. 

The Sessi onContext object stores information that you want to hold 
between calls to your EJB. WebLogic passes Sessi onContext to the 
setSessi onContext method. The Sessi onContext object is stored to a 
cl ass property, as we did in setSessi onContext. 



Creating deployment descriptors 

Deployment descriptors are the configuration files that allow WebLogic to 
know about your EJBs. WebLogic uses two EJB-specific deployment descrip- 
tors; both are XML files: 

I 

ej b - j a r . xml . Required by J2EE, this descriptor remains the same 
whether you're using WebLogic or another application server. The pri- 
mary purpose of this file is to map your bean to its class files and to 
define the type of bean. 

webl ogi cejb- jar . xml . This descriptor includes configuration infor- 
mation required by WebLogic but not by J2EE. This file is specific to 
WebLogic and would have no meaning to another application server. 
This file contains information for performance, clustering, and security. 

The ejbjar.xml descriptor required for the example stateless bean is 
shown in Listing 6-4. 



Listing 6-4: J2EE Deployment Descriptor for Your Stateless EJB 

<!D0CTYPE ejb-jar PUBLIC 

'-//Sun Microsystems, Inc. //DTD Enterprise JavaBeans 2.0//EN' 

'http://java.sun. com/dtd/ejb- jar_2_0 . dtd ' > 

<ejb-jar> 

<enterprise-beans> 
<sessi on> 

<e jb-name>Sampl eOb ject</ejb-name> 

<home)com.dummies.ejb. Sampl eHome</home> 
< remote) com . dummi es . e jb . Sampl e</ remote) 
<ejb-cl ass)com . dummi es . ej b . Sampl eBean</ej b - cl ass) 



(continued) 
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<session-type>Stateless</session-type> 
<transaction-type>Container</transaction-type> 
'session) 
</enterprise-beans> 
</ejb-jar> 



The elements you must configure are summarized in Table 6-1. The primary 
purpose of these elements is to name the home, interface, and bean classes 
that you created previously. 



Table 6-1 Selected EJB Deployment Descriptor Elements 



Element 


What It Is 






ejb-name 


The name of thf 


i EJB. 




home 


The class that implements the home interface for 
the bean. 


remote 


The class thatii 
for the bean. 


nplementsthe remote i 


nterface 


ejb-cl ass 


The class that implements the logic for 


the bean. 


sessi on-type 


The type of session that this bean supports. This 

valueisStatelessorStateful. 



transact!' on -type This property specifies whether the bean or the 

containerwill manage persistence for an entity 
bean. Should be contai ner or bean. See 
Chapter 7. 



In addition to the standard EJB deployment descriptor, you must create 
a WebLogic-compatible deployment descriptor. An example of a WebLogic 
deployment descriptor is shown in Listing 6-5. You must configure a number 
of elements, primarily enterprise elements. These are covered in Chapter 8. 



Listing 6-5: WebLogic Deployment Descriptor for Your Stateless EJB 

<!D0CTYPE weblogic-ejb-jar PUBLIC 

'-//BEA Systems, Inc. //DTD WebLogic 6.0.0 EJB//EN ' 

' http : //www .bea.com/servers/wls600/dtd/ we blogic-ejb-jar.dtd'> 

<webl ogi c-ejb-jar> 

<weblogic-enterprise-bean> 

<ejb-name>Sampl e0bject</e jb-name> 
<jndi -name>Sampl e0bject</ jndi -name) 
</weblogic-enterprise-bean> 
</webl ogi c-e jb- j ar> 
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point, you've focused on how to configure the application server, 
the reason you put an EJB on an application server is so a client 
program can access the functionality in the EJB. In this section, you create a 
client that can access your EJB. Listing 6-6 shows a simple client that 
accesses the EJB that you just created. 

When I refer to client and sewer, you may think that this means two different 
machines. This is not necessarily the case. The client and server could be the 
same machine. 



Listing 6-6: Java Program to Access Your Stateless EJB 

package com . dummi es . ejb ; 

import j avax . ej b . * ; 
import j avax . rmi . * ; 
import j ava . rmi . * ; 
import Java . uti 1 .*; 
import j avax . swi ng . * ; 
import j avax . nami ng . * ; 

public class SampleClient 
{ 

public static void mai n ( Stri ng[ ] args) 
{ 

try 

{ 

Properties h = new Properti es ( ) ; 

h . put (Context . INITIAL_CONTEXT_FACTORY , 

"webl ogi c. jndi .WLIni ti al Context Factory" ) ; 
h.put(Context.PROVIDER_URL, " t3 : //l ocal host : 7001 " ); 
Context initial = new I ni ti al Context ( h ); 
Object obj = i ni ti al . 1 ookup ( "Sampl eObject" ) ; 



SampleHome samplehome = (SampleHome) 
PortableRemoteObject.narrow(obj , Sampl eHome . cl ass ) ; 
Sample sample = sampl ehome . create( ) ; 
String str = 

JOpti onPane . showInputDi al og( " Enter your number"); 
JOpti on Pane . showMessageDi al og( null , 

sample.sampleMethod(Integer.parseInt(str)) ); 

) 

catch ( Except! on e) 
{ 

System . out . pri ntl n ( e ); 
JOpti on Pane . showMessageDi al og( nul 1 , 
" Except! on : "+e ) ; 

) 

) 

} 
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To access the EJB using the client program, you must first create a 
Properties object that will contain information specifying which WebLogic 
u will connect to: 



perties h = new Properti es ( ) ; 
h. put (Context. IN ITIAL_CONTEXT_FACTORY , 

"webl ogi c . jndi . WLI ni ti a 1 Context Factory " ) ; 
h.put(Context.PROVIDER_URL, " t3 :/ /l ocal host : 7001 " ); 

The server that you're connecting to is on port 7001 of the localhost server. 
The localhost address specifies the current computer. 

After you've constructed your properties, you must obtain a Context object. 
To obtain a Context object, you initialize IntialContext with the 



Properties object that you just created (h): 




Context initial 


= new Initial Context( h ); 




Now that you have a Context object, you car 


i use it to access your EJB: 


Object obj = i ni ti al . 1 ookup( " Sampl eOb ject " ) ; 

Sampl eHome sampl ehome = ( Sampl eHome ) 

Portabl eRemoteOb ject . narrow( obj , Sampl eHome . cl ass ) ; 




Finally, you're ready to create your EJB as an 
create method of the sampl ehome object: 


object. To do this, you call the 


Sample sample = 


sampl ehome 


.create ( ) ; 







Now that you have the object, you can use it. The user is prompted for a 
number, which is then passed to the sampl e object: 

String str = 

JOpti onPane . showInputDi al og (" Enter your number"); 
JOptionPane. showMessageDi al og ( nul 1 , 

sampl e . sampl eMethod( Integer.parselnt(str)) ); 

The result returned from the EJB is then displayed. As you can see from this 
example, you call the EJB just like any other Java object. The most complex 
part of creating EJBs on the client is obtaining the object. 



Building the Stateless Session Bean EJB 



In the preceding section, you created the files necessary to construct an EJB. 
In this section, you bring these files together and compile the EJB. The final 
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output from the compilation process is a JAR file. You can then deploy this 
JAR file to WebLogic Server, a process shown in the next section. 

^^b[^(^^rly compile the EJB, you must have J2SE and J2EE installed on your 
computer. You can download them from http : //Java . sun . com. These are 
two separate downloads. Make sure that you install J2SE first. 

Building an EJB requires several steps. To make this process easier, these 
steps are often put in a script file, which you can then execute to build the 
EJB JAR file whenever it's needed. To build the example, you would use a 
build script similar to the one shown in Listing 6-7. This script first compiles 
the Java files to class files. The EJB is then built from these class files. 



Listing 6-7: Script to Build Your Stateless EJB 

@rem buildStatelessEJB.cmd 
©echo off 

©rem Set this to the location of your JDK installation 
set JDK_H0ME=C:\j2sdkl.4.1_01 

@rem Set this to the location of your J2EE JAR file 
set CLASSPATH=C: \j2sdkeel .4\1 ib\j2ee. jar 

@rem Set this to the location for storing the class files 
set CLASSES=.\CLASSES 

@rem set up the directory structure 

rmdir /q /s %CLASSES% 

mkdir %CLASSES% 

mkdir %CLASSES°AMETA-INF 

@rem compile the classes 

"%JDK_H0ME%" \bi n\javac . \src\com\dummies\ejb\*. Java - 
classpath %CLASSPATH% -d %CLASSES% 

@rem copy the config files 

xcopy /y .\src\META-INF\*.* %CLASSES%\META-INF\ 

@rem JAR it up 
cd %CLASSES% 

"%JDK_HOMEr\bin\jar -cvf . . \EJBSampl e . jar *.* 
cd . . 

You should change the first few lines of the build script to reflect the correct 
paths on your computer. The first variable, J DK_H0ME, contains the directory 
that JDK was installed into. The second variable, CLASSPATH, contains a list 
of all external JAR files required to compile this class: 
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set JDK_H0ME=C:\j2sdkl.4.1_01 
set CLASSPATH=C: \j2sdkeel .4\1 ib\j2ee. jar 



external JAR file that's referenced is the J2EE JAR file. This file 
should have been installed automatically when you installed J2EE. 

Next, the path that the class files will be compiled to is set. Don't change this 
directory: 

@rem Set this to the location for storing the class files 
set CLASSES=.\CLASSES 



The script is now ready to create the directory structure. Ifaclasses 
directory already exists, it is deleted. Next, you create the classes directory 
as well as a directory named M ET A - 1 N F inside the classes directory. The 
META INF directory is where you will store the ejb-jar.xml and weblogic- 
ejb-jar.xml files: 



@rem set up the directory structure 

rmdir /q /s %CLASSES% 

mkdir %CLASSES% 

mkdir %CLASSES%\META-INF 



begin to compile the 


files: 








@rem compile the 
"%JDK_H0ME%" \bi n 


cl asses 
\javac .\s 


rc\com\dummies\ejb\*. Java 





classpath %CLASSPATM -d %CLASSES% 



Next, you copy the two XML files to the classes directory so that they can 
be included in the JAR file build: 



@rem copy the config files 

xcopy /y .\src\META-INF\*.* %CLASSES%\META-INF\ 



Finally, after all the code has been compiled, the script creates a JAR file to 
contain the entire EJB: 



@rem JAR it up 
cd %CLASSES% 

"%JDK_HOMEr\bin\jar -cvf . . \EJBSampl e . jar *.* 
cd . . 



When the process is finished, you're left with a file named EJBSample.jar. This 
file contains your EJB and will be used when the EJB is deployed. When you 
execute Listing 6-7, the screen shown in Figure 6-1 appears. 
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l E 

|C:' Ue bLogic Example s\cb6\e jb-sess ion >buildEJB I 
'■.Si rc^MF^-INFNejb-jar.xnl I 
II, S; r.\M TO INF\weblogic-e jb-jar.xnl 
It 1 i. ^<ss opied 
"xd( ed tk . est 

E dding: con/<in = 0> <out = 0Xstoi*ed 0X> 
dding: con/dunnies/< in = 0> <out = 0Xstoi*ed 0X> 
dding: con/dunnies/e jb/<in " 0> <out= 0Xstoi*ed 0>;> 
adding: con/dunnies/e jb/Counter.class(in = 281> <out= 197><deflated 29z> 
adding: con/dunnies/e jb/CounterBean .c lass < in = 891> <out= 456><deflated 48x> 
adding: con/dunnies/e jb/CounterClient . class < in = 2410> <out= 1314><def lated 45x> 

adding: con/dunnies/e jb/CounterHome .class < in = 277> <out= 197Xdef lated 28x> 
ignoring entt*y METfl-INF/ 

addin«: METft-INF/eib-.iar .xnKin = 538> <out= 270Xdeflated 49z> 



E dding: METfl-INF/weblogic-e jb-jai».xnl<in = 339> <out= 194Xdef lated 42z> 
: \UebLogicExanples\ch6\e jb-sess ion > 



Figure 6-1: 

Building 
the EJB. 



bepioyinq the Stateless Session EJB 

Now that you've created your stateless session EJB, you must deploy it. Then 
you can use the EJB in client programs. The following steps show you how to 
deploy the EJB: 

1. Start WebLogic Server. 

To do so, choose Starts All ProgramsOBEA WebLogic Platform 8.10 
User ProjectsOmyc/omaz'n. Replace mydomain with the name of the 
domain to which you want to deploy the EJB. 

2. Start WebLogic Server Console. 

To do so, access the URL http://localhost:7001/console. 

3. Type your user name and password. 

4. On the left, under your domain, click Deployments and then click EJB 
Modules. 

The screen shown in Figure 6-2 appears. 

5. Click the Deploy a new EJB Module link. 

6. In the Step 1 section, choose to upload the EJBSample.jar file by click- 
ing the upload filefs) link. 

After the upload, your JAR file is visible under Step 2. 

7. In the Step 2 section, select the EJBSample.jar file. 

8. In the Step 3 section, select your server from the Available Servers list 
and click the right arrow to move it to the Target Servers list. 

9. In the Step 4 section, type a name for the application. 

You can enter any name you like. To follow along with the example, type 
EJBSample. 
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Figure 6-2: 

Deploying 
the EJB. 



File Edit View Favorites Tools Help 



,3^iclebarFrameId=wl_console_frame_l 0484536007368M3ean=mydomain7o3AName7o3Dmydomain7o2CType7o3DDomain 



• Console 
□ mydomain 
S CJ Servers 
CJJ Clusters 
CjJ Machines 
0 Deployments 
CjJ Applications 
CJ EJB Modules 
_J Web Application Modules 
LJ Connector Modules 
CJJ Startup & Shutdown 
13 CJ Services 
B CJ Security 

CJ Domain Log Filters 
CJ Tasks 



Oftf 



Connected to : localhost 7001 | You are logged in as : admin | Logout 



VI o nit o ring 



An EJB module represents one or more Enterprise JavaBeans (EJBs) contained 
in an EJB JAR (Java Archive) file or exploded JAR directory. An EJB module can 
be deployed on one or more target servers or clusters. Configuring and deploying 
an EJB module in a WebLogic Server domain enables WebLogic Server to serve 
the modules of the EJB to clients. 

When one or more EJB modules are configured for deployment in the current 
WebLogic Server domain, this EJB Modules page displays key information 
about each of them. To configure an EJB module for deployment, click the 
Deploy a new EJB Module link. 

B^ Deploy a new EJB Module 



[<J_ 



e] Applet navapplet started 



* J Local intranet 



Start Server- "C:\be... 



3 WebLogic Server Con... 



10. Click Configure and Deploy to complete the process. 

Your EJB is now deployed and ready to be accessed. In the next section, you 
create a simple class that tests the EJB. 



Testing the Stateless Session EJB 

Now that you've created your EJB, you need a class that calls it. You created 
this class in Listing 6-6. Now you execute the class to see the stateless ses- 
sion EJB in action. Just as you did when building the EJB, you will also create 
a script that runs the EJB client. This program is shown in Listing 6-8. 



Listing 6-8: Script to Run Your Stateless EJB Client 

@rem runEJB.bat 
©echo off 

@rem Set this to the location of your JDK installation 
set JDK_H0ME=C:\j2sdkl.4.1_01 



©rem Set this to the location of your J2EE JAR file 

set CLASSPATH=C: \j2sdkeel .4\1 ib\j2ee. jar; . \EJBSampl e . jar ; 
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C : \bea\webl ogic81\server\li tAwebl ogi c . j a r 

^ ^^^-ani-^niTipi 1 e the classes 
| J [Q 1^ |*j 0 M E % " \bi n\ ja va com . dummi es . ejb . Sampl eCl i ent -classpath 

The process for running a class that makes use of EJBs is similar to the 
process you'd use for any other Java class. The only additional step that you 
must be aware of is making sure that the correct JAR files are in CLASSPATH: 

set CLASSPATH=C: \j2sdkeel .4\1 ib\j2ee. jar; . \EJBSampl e . jar ; 
C : \bea\webl ogic81\server\li b\webl ogi c . j ar 

If you issue this command, you'll have all three required JAR files in 
CLASSPATH. Of course, if you've stored these JAR files elsewhere, you must 
change the preceding path. 

You might need to change this CLASSPATH depending on the path structure of 
your computer. As you can see, you must include three JAR files: 

f J2EE JAR file (j2ee.jar) 

WebLogic JAR file (weblogic.jar) 
i>* EJB JAR file (for example, EJBSample.jar) 

For most EJB clients, you will need at least these three files. The name of the 
EJB JAR file depends on what you called the EJB for your own application. 



Adding State 

The EJBs that you've seen so far are stateless, which means they remember 
nothing from one page to the next. After the JSP on which you used the EJB 
has finished displaying, any data stored in the bean is lost. You can add state 
by creating a session EJB. 

A session EJB holds the information stored in the bean until the user's ses- 
sion is terminated. (A user's session is a special area of memory created for 
each user who logs on to the web server.) This session information allows 
the web server to store basic information about the current user. 

Although session EJBs are a convenient way to store information about a 
user, they should not be overused. Every piece of information that you add to 
the session bean is additional information that the web server must store for 
every user who logs on to the system. This can result in a large amount of 
data if your system has a large number of simultaneous users. 
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For the example session EJB, you'll create an EJB that implements a simple 
counter. The class, named Counter, contains three methods named count, 
dgetCount. The count method is called with an integer as the 
r. This integer is added to Counter's internal counter. To access 
the value in this counter, you call the getCount method. The counter holds 
its value as the EJB is used. You can use the reset method to set this count 
back to 0. 



You can specify an EJB as a session EJB with the J2EE deployment descriptor. 
Whereas Listing 6-4 is a deployment descriptor for a stateless EJB, Listing 6-9 
is a deployment descriptor for a session EJB. 



Listing 6-9: J2EE Deployment Descriptor for Your Session EJB 

<!D0CTYPE ejb-jar PUBLIC 

'-//Sun Microsystems, Inc. //DTD Enterprise JavaBeans 2.0//EN' 

'http://java.sun. com/dtd/ejb- ja r_2_0 . dtd ' > 

<ejb-jar> 

<enterpri se-beans> 
<sessi on> 

<e jb-name>CounterObject</ej b-name> 

<home>com.dummies.ejb. Counter Home</home> 
<remote>com. dummi es.ejb.Counter</ remote) 
<ejb-cl ass>com . dummi es .ejb.CounterBean</ejb-class> 
<sessi on -type>Statef ill </session-type> 
<transaction-type>Container</transaction-type> 
</sessi on> 
</enterprise-beans> 
</ejb-jar> 

The one line that changes an EJB to a session EJB is the session-type tag. 
Because the tag type is specified as Stateful, the EJB becomes a session EJB. 

Just as was the case with the stateless EJB, the session EJB must also have a 
WebLogic deployment descriptor. Listing 6-10 is a WebLogic deployment 
descriptor that works with the session EJB that you're creating. 



Listing 6-1 0: WebLogic Deployment Descriptor for Your Session EJB 

<!D0CTYPE weblogic-ejb-jar PUBLIC 

'-//BEA Systems, Inc. //DTD WebLogic 6.0.0 EJB//EN ' 

' http : //www .bea.com/servers/wls600/dtd/weblogic-ejb-jar.dtd'> 

<webl ogi c-ejb-jar> 

<weblogic-enterprise-bean> 

<ejb-name>CounterObject</ejb-name> 
<jndi -name>CounterObject</jndi -name> 
</weblogic-enterprise-bean> 
</webl ogi c-e jb- j ar> 
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The WebLogic deployment descriptor for a session EJB is the same as the 
one for a stateless bean. Aside from the difference in the name of the EJB 
£>|ni|a W)bject versus CounterObject), Listing 6-10 is the same as Listing 6-5. 



Now that the configuration files are out of the way, you can construct the EJB. 
Stateless and session EJBs have the same three Java files. The three files that 
implement the Counter interface are shown in Listing 6-11. 

Listing 6-1 1 : Remote Interface for Your Session EJB 

// Counter. java 

package com . dummi es . ejb ; 

import javax.ejb.*; 
import java . rmi . * ; 

public interface Counter extends EJBObject 
{ 

publ i c voi d reset( ) 

throws RemoteExcepti on ; 

public void countd'nt n) 
throws RemoteExcepti on ; 

public int getCountO 
throws RemoteExcepti on ; 

) 

Here the signatures are given for all three methods used by the Counter EJB. 
(The signature is the method header that specifies the method parameters, 
return type, and exceptions thrown.) The interface for a session EJB is no dif- 
ferent than that for a stateless EJB. 

The next file to be considered is the home class, which is shown in Listing 
6-12. Compare this listing with Listing 6-2, and you can see that the home 
class for a session EJB and a stateless EJB is the same. 

Listing 6-1 2: Home Interface for Your Session EJB 

// CounterHome . j ava 
package com . dummi es . ejb ; 

import javax.ejb.*; 
import java . rmi .*; 

public interface CounterHome extends EJBHome 
( 

public Counter createO 

throws RemoteExcepti on,CreateException; 




} 
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Next is the session bean class, where you place all the work performed by the 
session bean. This class, which is shown in Listing 6-13, must remember the 
ed in the session bean. 



Listing 6-1 3: Class for Your Session EJB 



// CounterBean . j ava 
package com . dummi es . ejb ; 

import javax.ejb.*; 

import Java . rmi . * ; 

import j avax . swi ng . * ; 

public class CounterBean implements SessionBean 



private Sessi onContext stx; 

//Required methods, not used by this type of bean 
public void ejbCreate( ) I ) 
public void ejbRemove( ) { ) 
public void ejbActi vate( ) { ) 
public void ej bPassi vate( ) { ) 

// setter for the Sessi onContext 

public void setSessi onContext ( Sessi onContext ctx) 

( 

ctx = this. stx; 



// the session information 
private int count = 0; 

// the sample method 

publ i c voi d reset( ) 
throws RemoteExcepti on 

{ 

count = 0; 



public void countd'nt n) 
throws RemoteExcepti on 

{ 

count+=n ; 



public int getCountO 
throws RemoteExcepti on 
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The session EJB uses properties, also known as class-level variables, to store 
the data that will be remembered. In the case of the Counter EJB, the session 
information is stored in the count variable, as seen here: 

private int count = 0; 

Next you see how to call the session bean. The process is similar to calling a 
stateless EJB. The client program calls the session bean. The client is shown 
in Listing 6-14. 



Listing 6-14: Client for Your Session EJB 

// CounterCl ient . Java 
package com . dummi es . ejb ; 

import javax.ejb.*; 
import j avax . rmi . * ; 
import Java . rmi . * ; 
import Java . uti 1 . *; 
import j avax . swi ng . * ; 
import j avax . nami ng . * ; 

public class CounterCl i ent 
{ 

public static void mai n ( Stri ng[ ] args) 
{ 

try 

f 

Properties h = new Properti es ( ) ; 

h . put ( Context . INITIAL_C0NTEXT_FACT0RY , 

"webl ogi c . jndi . WLIni ti al Con text Factory " ) ; 
h.put(Context.PROVIDER_URL, " t3 : //l ocal host : 7001 " ); 
Context initial = new I ni ti al Context ( h ); 
Object obj = i niti al . 1 ookup( "CounterObject" ) ; 

CounterHome counterhome = ( CounterHome ) 
PortableRemoteObject.narrow(obj , CounterHome . cl ass ) ; 
Counter counter = counterhome . create( ) ; 

int i = 1 ; 

while(i !=0) 

{ 



(continued) 
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String str = 

JOpti onPane . showInputDi al og (" Enter your number") 
i f ( str==nul 1 ) 

i=0; 
el se 

i = Integer. parselnt(str) ; 
counter . count( i ) ; 

JOpti on Pane. showMessageDi al og(null , 

"Current count = " + counter . getCount( ) ); 

) 

System . exi t ( 0 ) ; 

) 

catch ( Excepti on e) 

{ 

System . out . pri ntl n ( e ); 
JOpti on Pane . showMessageDi al og( nul 1 , 
" Excepti on : "+e ) ; 

) 



Session and stateless EJBs are instantiated in the same way. (Instantiation is 
the process by which the EJB is allocated and assigned to a variable.) All 
information about the fact that this is a session bean is contained in the EJB 
itself. 



The client program works by displaying a dialog box in which the user types 
a number. As the user types more and more numbers, they're added to the 
counter bean. This program can be seen in Figure 6-3. 



Figure 6-3: 

Testing the 
stateless 
EJB. 







i v, Enter your number 

oj | | 


OK Cancel 









Accessing Data utith Entity Beans 

One powerful feature of EJBs is their capability to represent data stored in 
relational databases. This type of bean is called an entity bean. The process 
of storing this data is called persistence. Two types of entity beans follow: 
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i>* Bean-managed persistence (BMP). BMP EJBs contain code inside the 
bean class that allow the beans to be persisted. The beans may be per- 
d to a relational database or some other source. If the beans are 
isted to a relational database, the EJB classes will contain methods 
used to write the contents of the bean to the database. If a means other 
than a relational database is used to persist the beans, the appropriate 
methods must be included. 



f* Container-managed persistence (CMP). CMP EJBs don't contain code 
inside their classes to persist the data stored in them. Rather, CMP EJBs 
are persisted to a relational database by using the SQL commands 
embedded in the EJB's configuration files. 



Chapter 7 describes how to use both types of beans to interact with your 
database and shows you how to decide which of the two types you should 
use in your programs. 



Configuring Me$$age*Dri(/en Beans 

The EJBs discussed up to this point are all accessed like normal Java objects. 
You can also configure EJBs to be accessed through messages. Using mes- 
sages with EJBs requires Java Message Services (JMS). This type of EJB is dis- 
cussed in Chapter 15. 
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In This Chapter 

Accessing databases the WebLogic way 
Understanding the life cycle of a bean 
Constructing and compiling a BMP bean 
Constructing and compiling a CMP bean 

••••••••••••••••••••••••••••••••••••••••••••••••a 

f 

■ n this chapter, you discover how to use J2EE entity beans. Entity beans 

provide a convenient interface between your program and the database. 
These beans are used to hold data that must eventually be stored in some 
permanent form, most commonly a relational database. J2EE has two types of 
entity beans: bean-managed persistence (BMP) beans and container-managed 
persistence (CMP) beans. BMP entity beans open connections directly to the 
database, whereas CMP entity beans rely on the server (container) for inter- 
acting with the database. I discuss both types of beans in this chapter. 

Understanding WebLogic 
Database Access 

The purpose of an entity bean is to allow Java data to move between memory 
and permanent storage, such as a database. The entity bean examples in this 
chapter write their data to a database, so you need to understand the basics of 
connecting a database to WebLogic. A basic familiarity with SQL and relational 
databases is assumed. A book such as Allen G. Taylor's SQL For Dummies (pub- 
lished by Wiley Publishing, Inc.) would be helpful for understanding the finer 
points of SQL. 
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You can use nearly any sort of database with WebLogic. For the examples in 
this book, I use the ODBC-JDBC bridge driver. Open Database Connectivity 
js a common standard on the Microsoft platform. Java Database 
_frvity (JDBC) is the Java database standard. Using the ODBC-JDBC 
bridge allows you to use ODBC drivers from Java. Everything that you need 
to use the ODBC-JDBC bridge is already built into Java. 



If you're using a database such as Oracle, DB2, MySQL, or SQL Server, you 
should use the appropriate driver. This will give better performance than the 
ODBC-JDBC bridge. For specific instructions on how to use a particular data- 
base with JDBC, refer to that database's documentation. Database access is 
covered in Chapter 12. More information about MySQL can be found at 
http : //www .mysql .org. 

Regardless of which database you use, you must set up the appropriate 
tables. In SQL, a table is a database construct that holds individual rows. For 
example, if you were keeping an address book, the address book is the table 
with individual names stored in rows. Listing 7-1 shows the SQL code neces- 
sary to create the tables used in this chapter. For more information about 
SQL, see Chapter 12. 



Listing 7-1 : Script to Create the Example Database 



CREATE TABLE T STUDENT ( 
F ID INTEGER NOT NULL P 
F FIRST VARCHAR(40), 
F_LAST VARCHAR(40)) 


R 


IMARY KEY, 




CREATE TABLE T DEPARTMENT 
F ID INTEGER NOT NULL P 
F NAME VARCHAR(40)) 


( 

RIMARY KEY, 




CREATE TABLE T COURSE ( 

F ID INTEGER NOT NULL PRIMARY KEY, 
F NAME VARCHAR(40) , 
F CRFDTT T NTFGFR . 


F_DEPARTMENT_I D INTEGER 


NOT NULL) 



The SQL in Listing 7-1 should be generic enough to work with most data- 
bases. Note that each table name is prefixed with T_ and each field name is 
prefixed with F_. This notation ensures that a table or field name does not 
accidentally use a reserved word. This is important when designing for multi- 
ple databases, in which the collection of reserved words is different from 
database to database. 

As you can see from Listing 7-1, each table is made up of several fields. For 
example, T_DEPARTMENT holds F_I D and F_NAME as fields. Every row in the 
T_DEPARTMENT table will hold these two values. 
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Creating the connection pool 



.c communicates with the database through a connection pool. The 
on pool enables WebLogic to use a fixed number of connections to 
databases rather than incur the overhead of constantly creating and dispos- 
ing of connections. Because of this, you must establish a data connection 
pool that accesses your database. To do so, follow these steps: 

1. Start Administrative Console. 

For more information on this step, see Chapter 4. 

2. On the left side of the screen, click the Services folder, and then click 
the JDBC folder. 

On this page, you can choose connection pools and choose to create a 
connection pool. 

3. Type a name for the connection pool. 

To follow along with the example, type SchoolPool for the connection 
pool name. This name needs to be given to the data source you create in 
the next section. 

4. Choose your database type. 

Your database type should match the database you're using. To follow 
along with the example, choose Other. 

5. Set the driver class name and URL to whatever is appropriate for your 
database. 

The driver class name and URL in Figure 7-1 are for an ODBC DSN named 
school. 

6. Add this pool to your server. 

To do so, click the Targets tab. Select your server, and then click the 
right arrow button to assign it. 



Creating the data source 

After you create a connection pool, you must attach it to a data source. It is 
through this data source that WebLogic can access your database. To create 
a data source, follow these steps: 

1. In Administrative Console, click the Services folder and then click the 
data source you want to use. 

If you choose the JDBC data source, the screen shown in Figure 7-2 
appears. 



Part II: Understanding WebLogic Components 



SS] WebLogic Server Console Microsoft Internet Explore! 




Figure 7-1: 

Create a 
connection 
pool. 



File Edit View Favorites Tools Help 



t^Media 0'%,\SO 



sidebarFrameId=wl_console_frame_l 04906631 1901&MBean=mydomain%3AName%3Dmydomain%2CType%3DDomain 



• Console 



H mydomain 
0 □ Severs 

□ Closters 

□ Machines 

0 □ Deployments 
□ '^3 Services 

□ jCOM 
B 3 JDBC 

□ Connection Pools 

□ MultiPools 

□ Data Sources 

□ Data Source Factories 
0 □ JMS 

0 □ Messaging Bridge 

□ XML 
O JTA 

SQSNMP 

□ vVTC 

□ wLEC (deprecated) 

□ jolt 

□ Virtual Hosts 

□ Mail 

□ FileT3 



Define and test connection 

Name your new connection pool and define connection properties. You 
can optionally test a database connection using the properties you 
define. 



Nome: 



SchoolPool 



The name of this JDBC connection pool. 
Connection Properties 

Dtivei ClBMiame: sun.jdbc.odbc.JdbcOdbcDriver 



The full package name of JDBC driver class used to create the physical 
database connections in the connection pool. 



jdbc:odbc:school 



The URL of the database to connect to. The format of the URL varies by 
JDBC driver. 



Database Usei Name: 
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mydomain> JDBC Data Sources> C 



You are logged in as : admin | Logout 



Configure the data source 

Define your new JDBC data source. 



Name: MyJDBC Data Source 

The name of this JDBC data source. 



JHDI N.iine 



< 



The JNDI path to where this JDBC data source is bound. 
0 Honoi Global Tiansactions 

Specifies whether this data source will participate n existing global (XAj 
transactions. Unchecking this option while creating the data source 
should be done rarely and with care. This option can not be changed 
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2. Type a name for your data source. 

You can choose any name you want; the name is for your reference only, 
a JNDI name. 



To follow along with the example, type jdbc/SchoolDataSource for the 
JNDI name. 

4. Type a pool name. 

This is the name you typed in Step 3 in the preceding section. To follow 
along with the example, type SchoolPool for the pool name. 

5. Add this data source to your server. 

To do so, click the Targets tab. Select your server, and then click the 
right arrow button to assign it. 



The life cycle of a bean 



Two types of beans are available for your use: 
bean-managed persistence (BMP) and con- 
tainer-managed persistence (CMP). With BMP 
beans, the bean handles the process of saving 
data. With CMP beans, the container, in this 
case WebLogic, handles the saving of bean 
data. In addition, CMP beans, unlike BMP 
beans, allow relationships between beans. 

Regardless of which type of bean you use, it's 
helpful to understand the EJB life cycle, which 
represents the stages that an entity bean goes 
through as it's used. 

The first step in an entity bean's life is its cre- 
ation by WebLogic. When the bean is created, 
the newlnstance method is called. This call 
is followed by a call to setEnti tyContext, 
which gives the entity bean access to 
WebLogic. At this point, the bean doesn't con- 
tain data. It has just been created and is said to 
be in a poo/ec/ state. 

To create a new instance of the entity bean, you 
call a create method in the bean's home inter- 
face. Before the bean can be useful, it must load 
its data from the database or become a new 
object. To load an existing bean, you make a 



call to a f i ndBy method in the bean's home 
interface. (Both methods are discussed in this 
chapter.) 

Now that the bean has been created or loaded, 
it's ready for use. At this point, the programmer 
can read data from the bean or change the field 
values held inside the bean. 

The bean can revert from a ready state to a 
pooled state in three ways: 

You can call the ejbPassive method, 
which disassociates the bean from the per- 
sistent data. The bean is now free to be 
used for another purpose. 

j*" You can call the remove method, which 
removes the bean from permanent storage. 

*<" You can roll back the transaction. A roll- 
back allows all the steps to either fail or 
succeed as a whole. 

As you create BMP and CMP beans, you'll see 
thatthe entity bean classes are similar. This can 
make creating EJBs by hand tedious. To allevi- 
ate this, use a development tool, such as 
Borland JBuilder or WebLogic EJBGen,to auto- 
matically generate your entity bean classes. 
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Now that you've set up the database connection, you're ready to use beans 
that interact with that database. 
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Constructing a BMP Bean 



The first entity bean you'll create is a BMP bean that represents a student. 
You can use the student BMP bean to store and retrieve information about 
students at a school. With a BMP bean, the bean class performs all the SQL 
needed to read the object from and write the object to the database. Several 
source files are needed to create a BMP bean. In this section, you find out 
how to create each of them, starting with the bean interface. 



Constructing the bean interface 

The bean interface is what a programmer who is using your bean has access 
to. Listing 7-2 shows the student bean interface. The bean interface contains 
mainly getters and setters for the student data: getld, getFirst, getLast, 
s e t F i r s t , and setLast. ID doesn't have a s e t method because it's the pri- 
mary key in the database — the value that uniquely identifies the student — 
and can't be changed. 



Listing 7-2: Student Bean Interface 

package com . dummi es . ejb ; 

import j avax . ejb . EJBObject ; 
import java . rmi . RemoteExcepti on ; 

public interface Student extends EJBObject { 
public int getldO throws RemoteExcepti on ; 
public String getFirstO throws RemoteExcepti on ; 
public void setFi rst ( Stri ng first) throws RemoteExcepti on ; 
public String getLastO throws RemoteExcepti on ; 
public void setl_ast(String last) throws RemoteExcepti on ; 

) 



Constructing the home interface 

The home interface is used to gain access to student entity beans. The main 
task of the student home interface, which is shown in Listing 7-3, is to create 
and access objects. Creating objects is accomplished by calling one of the 
create methods . You should provide one create method for each of the 
methods in which you would like to create an entity bean. By methods, I mean 



Chapter 7: Using Entity Beans 



jpBoote 



the data that you would like to provide to create your bean. You may create a 
method that accepts all the necessary information, and a second method that 
o information and creates a blank bean. 



Listing 7-3: Student Home Interface 



package com . dummi es . ejb ; 

import javax.ejb.*; 

import Java . rmi . RemoteExcepti on ; 

import java.util .Enumeration; 

public interface StudentHome extends EJBHome { 
public Student create( Integer key) 
throws CreateExcepti on , RemoteExcepti on ; 
public Student create( Integer key, String first, String 
last) 

throws CreateExcepti on , RemoteExcepti on ; 
public Student fi ndByPrimaryKey ( Integer key) 
throws Fi nderExcepti on , RemoteExcepti on ; 
public Enumeration findAllO 
throws Fi nderExcepti on , RemoteExcepti on ; 



In addition to the create method, there are two f i nd methods. The 
f i ndByPrimaryKey method locates students based on their primary key 
which is their student number. The f i ndAl 1 method returns all student 
records in the system. 



Constructing the bean implementation 

Perhaps the most important file to a BMP bean is the bean implementation 
file. When the bean is used by a client program, this file performs the main 
functions of the bean, namely storing and loading data. Listing 7-4 shows the 
student bean implementation. 



Listing 7-4: Student Bean Implementation 

package com . dummi es . ejb ; 

import javax.ejb.*; 

import j avax . nami ng . * ; 

import javax.sql .*; 

import j ava . sql . * ; 

import java . rmi . RemoteExcepti on ; 

import j ava . uti 1 . Vector ; 



(continued) 
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i|ri|3p_rt j ava . uti 1 . Enumerati on ; 

class StudentBean implements EntityBean 
private Enti tyContext context; 



// student attributes 
private int id; 
private String first; 
private String last; 

public int getldO ( return id;) 

public String getFirstO ( return first;) 

public void setFi rst ( Stri ng first) { this. first = first;) 

public String getLastO I return last;) 

public void setl_ast(String last) { this. last = last;) 

public void setEntityContext(EntityContext context) { 

this. context = context;) 
public void unsetEntityContext( ) ( this. context = null;) 

public void ejbActivate( ) {) 
public void ejbPassivate( ) {) 
public void ejbPostCreate( Integer id) {) 
public void ejbPostCreateC Integer id, String first, String 
last) I) 



public Integer ejbCreate( Integer key) throws 
CreateExcepti on { 
return e jbCreate ( key , "",""); 

) 

public Integer ejbCreate( Integer key, String first, String 
last) throws CreateExcepti on ( 
// set the beans fields 
this. id = key . i ntVal ue( ) ; 
this. f i rst = f i rst ; 
thi s . 1 ast = last; 
Connection conn = null; 
Prepa redStatement ps = null; 

try { 

conn = getConnecti on ( ) ; 

String sql = "INSERT INTO t_student ( f_i d , f_first, 

Oast) VALUES(?, ?,?)"; 
ps = conn . prepareStatement( sql ) ; 
ps . set Int ( 1 , i d ) ; 
ps.setString(2, first); 
ps . setStri ng( 3 , 1 ast ) ; 
ps .executeUpdate( ) ; 
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catch ( Exception e ) { 
System . out . pri ntl n (" Error : " + e ); 
e . pri ntStackTrace( ) ; 

throw new CreateExcepti on ( e . getMessage( ) ) 
finally { 
handleCleanup(conn,ps,null ) ; 



return key; 



public void ejbLoadO I 
Connection conn = null; 
PreparedStatement ps = null; 
Resul tSet rs = null; 



try ( 

Integer key = ( Integer ) context . getPrima ryKey( ) ; 
conn = getConnecti on ( ) ; 

String sql = "SELECT f_id, f_f i rst , f_l ast FROM 

t_student WHERE f_id=?" ; 
ps = conn . prepareStatement( sql ) ; 
ps.setlntd, key . intValueO); 
rs = ps .executeQuery( ) ; 

if ( ! rs . next( ) ) { 

// not found in database 

throw new NoSuchEnti tyExcepti on ( ) ; 

) 

// set the beans fields with the data from the DB row 
thi s . i d = rs . getlnt( 1 ) ; 
this. first = rs . getStri ng( 2 ) ; 
this. last = rs . getStri ng(3 ) ; 
) catch ( Exception e ) I 
System . out . pri ntl n (" Error : " + e ); 
e . pri ntStackTrace( ) ; 

throw new EJBExcepti on ( e . getMessage ( ) ) ; 
) finally { 
handleCleanup(conn,ps,rs); 



public void ejbStoreO { 
Connection conn = null; 
PreparedStatement ps = null; 

try { 

conn = getConnecti on () ; 

String sql = "UPDATE t_student SET f_f i rst=? , f_l ast=? 

WHERE f_id=? " ; 
ps = conn . prepareStatement( sql ) ; 
ps.setStringd, first); 



(continued) 
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ps . setStri ng( 2 , 1 ast ) ; 
ps . set Int ( 3 , i d ) ; 
'ps .executeUpdate( ) ; 
) catch ( Exception e ) ( 
System . out . pri ntl n (" Error : " + e ); 
e.printStackTraceO; 

throw new EJBExcepti on ( e . getMessage ( ) ) 
) finally { 

handleCleanup(conn,ps,null ) ; 



public void ejbRemove( ) throws RemoveExcepti on { 
Connection conn = null; 
PreparedStatement ps = null; 

try { 

conn = getConnecti on ( ) ; 

String sql = "DELETE FROM t_student WHERE f_id=?"; 
ps = conn . prepareStatement( sql ) ; 
ps . set Int ( 1 , i d ) ; 
ps .executeUpdate( ) ; 
) catch ( Exception e ) I 
System . out . pri ntl n (" Error : " + e ); 
e . pri ntStackTrace( ) ; 

throw new RemoveExcepti on (e . getMessage( )) ; 
) finally { 

handleCleanup(conn,ps,null ) ; 

) 

) 



public Integer ejbFindByPrimaryKey( Integer key) throws 
Fi nderExcepti on { 
Connection conn = null; 
PreparedStatement ps = null; 
Resul tSet rs = null; 
try { 

conn = getConnecti on () ; 

String sql = "SELECT f_id FROM t_student WHERE f_id=?"; 
ps = conn . prepareStatement( sql ) ; 
ps.setlntd, key .intValueO); 
rs = ps .executeQuery( ) ; 
if ( ! rs . next( ) ) { 

throw new Ob jectNotFoundExcepti on ( ) ; 

) 

) catch ( Exception e ) I 
System . out . pri ntl n (" Error : " + e ); 
e.printStackTraceO; 

throw new Fi nderExcepti on (e . getMessage( )) ; 
) finally { 

handleCleanup(conn,ps,rs); 
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return key; 



Tc Enumeration ejbFi ndAl 1 ( ) throws Fi nderExcepti on { 
Connection conn = null; 
Prepa redStatement ps = null; 
Resul tSet rs = null; 
Vector keys = nul 1 ; 
try { 

conn = getConnecti on ( ) ; 

String sql = "SELECT f_id FROM t_student ORDER BY 
f_i d " ; 

ps = conn . prepareStatement( sql ) ; 
rs = ps .executeQuery( ) ; 
keys = new Vector( ) ; 
while ( rs.nextO ) I 

keys .add(new Integer(rs.getlntd))); 

) 

) catch ( Exception e ) I 
System . out . pri ntl n (" Error : " + e ); 
e.printStackTraceO; 

throw new Fi nderExcepti on (e . getMessage( )) ; 
) finally { 
handleCleanup(conn,ps,rs); 

) 

return keys . el ements ( ) ; 

) 



// internal utility methods 



private Connection getConnecti on ( ) throws Nami ngExcepti on , 

SQLException { 
InitialContext ic = new I ni ti al Context () ; 
DataSource ds = 

(DataSource)ic.lookup("java:comp/env/jdbc/SchoolDa 

taSource" ) ; 
return ds . getConnecti on () ; 



private void handl eCl eanup( Connecti on 

conn , PreparedStatement ps,ResultSet rs) 

{ 

// make sure the connection is returned to the connection 
pool 

try { 

if ( rs!=null ) 

rs . cl ose ( ) ; 
if ( ps!=null ) 

ps . cl ose ( ) ; 
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if ( conn!=null ) 

conn . cl ose( ) ; 
'catch ( SQLException e ) 



Two methods deal directly with the data source: getConnection and 
handl eCl eanup. The getConnecti on method opens a connection to the 
data source that you created earlier in this chapter. This connection is 
returned to the method that called getConnecti on. All methods in the bean 
implementation class call getConnecti on to gain access to the database. 
The handleCleanup method closes the database objects created by these 
methods. 



Also implemented in this file are various find methods as well as methods 
that handle the creation, deletion, modification, and retrieval of the student 
records. Most of these methods do no more than use JDBC and SQL to access 
the correct data. Chapter 12 covers JDBC in greater detail. 



Constructing the bean confirmation files 

Finally the BMP bean requires two configuration files. The first file, ejb- 
jar.xml, is a J2EE standard file. It's shown in Listing 7-5. 

Listing 7-5: Student J2EE Configuration File 

<?xml version="l .0"?> 

<!D0CTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc. //DTD 
Enterprise JavaBeans 1.1//EN' 

'http://java.sun. com/ j2ee/dtds/ej b- ja r_l_l . dtd ' > 

<ejb-jar> 

<enterprise-beans> 
<enti ty> 

<ejb-name>StudentObject</ejb-name> 

<home>com . dummi es . ejb . StudentHome</home> 

<remote>com.dummies.ejb.Student</remote> 

<ejb-class>com. dummi es.ejb.StudentBean</ejb-class> 

<persi stence- type) Bean< /per si stence- type) 

<prim- key-cl ass)java.1ang.I nteger</prim - key-cl ass) 

<reentrant)False</reentrant> 

<resource- ref > 

<descri pti on)The reference to the 

DataSource.</description> 
<res-ref-name>jdbc/School Da t a Sou rce</ res- ref -name) 
<res-type)javax.sql.DataSource</res-type> 
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<res-auth>Container</res-auth> 
</resource-ref > 
enti ty> 

iterpri se-beans> 
sembly-descri ptor> 
<container-transaction> 
<method> 

<ejb-name>StudentObject</ejb-name> 
<method-name>*</method-name> 
</method> 

<trans-attribute>Required</trans-attribute> 
</container-transaction> 
</assembly-descri ptor> 
</ejb-jar> 

This XML file has many settings, all of which are summarized in Table 7-1. 



Table 7-1 



J2EE Settings for BMP Beans 



Entry 


What It Is 






ejb-cl ass 


The name of the bean implementation class. This 
should be a full package name such as com . 



my company. My ImplementationCl ass. 



ejb-name 



The name of this bean. This can be any name, but it 
should not be duplicated elsewhere in your program. 



home 



The name of the home class. This should be a full 
package name such as com .my company . 
MyHomeCl ass. 



persi stence-type 



The type of persistence supported. This will be bea n 
for BMP and contai ner for CMP. 



prim- key -cl ass 



The type used by the primary key. This will usually be 
one of the wrapper classes, such as j ava . 1 ang . 

Integer or java.lang.String. 



reentrant 



Whether the class thread is safe. As long as you don't 
call classes that are not thread safe or use static 
variables, your code should be thread safe. 



remote 



The name of the bean interface. This is the class that 
implements the bean. 



res- ref -name 



The data source to use. You set up this data source in 
Administration Console. 



res-type 



The object type of this data source. This is almost 
always javax . sql .DataSource. 
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In addition to the J2EE standard configuration file, WebLogic adds some con- 
figuration information that you must also provide. You store this information 
blogic-ejb-jar.xml file, which is shown in Listing 7-6. Only a few addi- 
figuration items are stored in this file. The most important addi- 
tional piece of information for a BMP bean is the JNDI name, which your 
client programs use to access the bean. 



Listing 7-6: Student WebLogic Configuration File 

<?xml versi on=" 1 . 0" ?> 

<!D0CTYPE weblogic-ejb-jar PUBLIC W/BEA Systems, Inc. //DTD 
WebLogic 5.1.0 EJB//EN ' 

' http : //www .bea.com/servers/wls510/dtd/weblogic- 
ejb-jar.dtd' > 

<webl ogi c-ejb-jar> 

<weblogic-enterprise-bean> 

<ejb-name>StudentObject</ejb-name> 
<reference-descriptor> 
<resource-description> 

<res-ref-name>jdbc/StudentDataSource</res-ref-name> 
<jndi -name>StudentDataSource</jndi -name> 
</ resource -description) 
</ref erence-descri ptor> 
<jndi -name>StudentObject</jndi -name> 
</weblogic-enterprise-bean> 
</weblogic-ejb-jar> 



Compiling a BMP Bean 

You've seen how to construct the BMP bean, so now you're ready to compile 
and test it. To do this, you need to construct a client program. This client 
program will create an instance of the bean and cause it to load its data from 
the database. Listing 7-7 is a short client prog ram that uses the BMP bean. 



Listing 7-7: Client Program 

package com . dummi es . ejb ; 

import javax.ejb.*; 
import j avax . rmi . * ; 
import Java . rmi . * ; 
import Java . uti 1 .*; 
import j avax . swi ng . * ; 
import j avax . nami ng . * ; 



public class StudentCl i ent { 

public static void mai n ( Stri ng[ ] args) 
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try { 

Properties h = new Properti es ( ) ; 
,h . put (Context . INITIAL_CONTEXT_FACTORY , 

"webl ogi c . jndi . WLIni ti al Con text Factory " ) ; 
h.put(Context.PROVIDER_URL, "t3 : //I ocal host : 7001 " ); 
Context initial = new I ni ti al Context ( h ); 
Object obj = i niti al . 1 ookup( "StudentObject" ) ; 



StudentHome studentHome = ( StudentHome ) 



Portabl eRemoteOb ject . narrow ( obj 
StudentHome .class); 



// First attempt to locate student number 1 
Student student = nul 1 ; 



try I 

student = studentHome . fi ndByPrimaryKey ( new 
Integer( "1" ) ) ; 
) catch ( Fi nderExcepti on e ) { 

System . out . pri ntl n ( "Does not yet exist" ); 

) 



if ( student ! =nul 1 ) { 

System . out . pri ntl n ( "User already existed, delete 

him!"); 
student . remove( ) ; 

) 



student = studentHome. create(new 

Integer( "1" ) , "John" , "Smith" ) ; 
Sy st em. out. pri ntl n ( " Created user"); 
student. setLast( "Jones" ) ; 

System . out . pri ntl n ( "Change user's last name to Jones"); 
System . out . pri ntl n ( "Now find user by primary key"); 
try { 

student = studentHome . fi ndByPrima ryKey( new 
IntegerC "1" ) ) ; 
) catch ( Fi nderExcepti on e ) I 

System . out . pri ntl n ( "Something is not working, we did 
not fi nd him ! " ) ; 

) 

System . out . pri ntl n (" Found : " + student . getl_ast( ) + "," + 
student . getFi rst ( ) ) ; 



) catch ( Exception e ) I 
System . out . pri ntl n ( e ); 
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JOpti on Pane . showMessageDi al og(nul 1 , 

" Excepti on : "+e ) 



The client program first gains access to the home interface for the bean. 
(Home interfaces are discussed in Chapter 6.) After the home interface is 
accessed, you can create and load beans. The program begins by trying to 
load a student record with the ID number of 1. If the load is successful, the 
student record is deleted. Next, a new student record with an ID of 1 is cre- 
ated. This student's last name is then modified and resaved. The last name is 
modified as an example of how to process a change such as a correction. 

Listing 7-8 shows a script that compiles the CMP bean into a JAR file. For 
more information on this process, see Chapter 6. 



Listing 7-8: Script to Compile the Student EJB 



©echo off 

@rem Set this to the location of your JDK installation 
set JDK_H0ME=C:\j2sdkl.4.1_01 

@rem Set this to the location of your J2EE JAR file 
set CLASSPATH=C: \j2sdkeel .4\1 ib\j2ee. jar 

@rem Set this to the location where the class files will be 

stored 
set CLASSES=.\CLASSES 

@rem set up the directory structure 

rmdir /q /s %CLASSES% 

mkdir %CLASSES% 

mkdir %CLASSES%\META-INF 

©rem compile the classes 

"%JDK_H0ME%" \bi n\javac . \src\com\dummies\ejb\*. Java - 
classpath %CLASSPATH% -d %CLASSES% 

@rem copy the config files 

xcopy /y .\src\META-INF\*.* %CLASSES%\META-INF\ 

@rem JAR it up 
cd %CLASSES% 

"%JDK_HOME%"\bin\jar -cvf . . \BMPBean . jar *.* 
cd . . 



After you've built the JAR file, you must deploy it. For more information on 
this task, see Chapter 6. After the bean has been deployed, you can test it. 
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Listing 7-9 shows how to properly set up cl ass path so that the client pro- 
gram can run. 



-9: Script to Test the Student EJB 



©echo off 

@rem Set this to the location of your JDK installation 
set JDK_H0ME=C:\j2sdkl.4.1_01 

@rem Set this to the location of your J2EE JAR file 
set CLASSPATH=C: \j2sdkeel .4\1 ib\j2ee. jar; 
.\BMPBean.jar;C:\bea\weblogic81\server\lib\weblogic.jar 

@rem run the test client 

"%JDK_H0ME%" \bi n\ ja va com . dummi es.ejb.CMPClient -classpath 
%CLASSPATH% 



Constructing a CMP Bean 

As you saw in the preceding section, BMP beans must be saved and loaded 
by the bean itself. In this section, you find out about CMP beans as well as the 
capability of establishing relationships between CMP beans. The main differ- 
ence between a CMP bean and a BMP bean is that a BMP bean stores its own 
data, but a CMP bean uses WebLogic to store its data. As a result, the CMP 
bean has less code than the BMP bean. 

You'll create two CMP beans called Department and Course and give the 
Department class a one-to-many relationship with the Course class. 



Constructing the Value objects 

As was the case with a BMP bean, several classes make up a CMP bean. 
However, a CMP bean has a few additional class types. One of these is the 
value object. Value objects in a CMP bean have only one job: storing all data 
contained by the bean. The value object beans for both Course and 
Depa rtment are shown in Listings 7-10 and 7-11. 



Listing 7-10: Value Object for Course 
package com . dummi es . ejb ; 

public class CourseVO implements Java . i o . Seri al i zabl e { 
private Integer id; 
private String name; 
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pjMvate int credit; 
i c CourseVCK ) { 



public CourseV0( Integer id) 
this .id = id; 



public Integer getldO I 
return id; 



public void setName(String name) { 
this. name = name; 



public String getNameO { 
return name; 



public void setCredi t ( i nt credit) 
this. credit = credit; 



public int getCreditO { 
return credit; 



Listing 7-11: Value Object for Department 



package com . dummi es . ejb ; 

public class DepartmentVO implements Java . i o . Seri al i zabl e 
private Integer id; 
private String name; 

public DepartmentVCK ) 

{ 

) 

public DepartmentVCK Integer id) 
{ 

this .id = id; 



public Integer getldO 
{ 

return id; 
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} 

ic void setName(String newName) 

me = newName; 

) 

public String getNameO 
{ 

return name; 

) 

} 



Constructing the local bean interfaces 

EJB 2.0 introduced the concept of local and remote interfaces. The main pur- 
pose of these interfaces is to alleviate some of the overhead in having to call 
every bean as though it were on a remote computer. Both the Course and 
Department beans use local bean interfaces. 

For the local interface to work, the bean must be called from the same Java 
Virtual Machine (JVM) as the client program. This eliminates all overhead in 
calling from one JVM to another. The Department and Course examples use 
the local interface to enable fast access between the Department and Course 
classes. The local interface for the Course and Department classes are 
shown in Listings 7-12 and 7-13, respectively. 



Listing 7-12: Local Bean Interface for Course 



package com . dummi es . ejb ; 
import javax.ejb.*; 

public interface CourseLocal extends EJBLocal Object ( 
public CourseVO getCourseData ( ) ; 
public void setCourseData (CourseVO course); 

public void setDepartment(Departmentl_ocal dept); 
public DepartmentLocal getDepartment( ) ; 

) 



Listing 7-13: Local Bean Interface for Department 



package com . dummi es . ejb ; 
import javax.ejb.*; 

public interface DepartmentLocal extends EJBLocal Object { 
) 
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courses to itself. No local methods are made public in Depa rtment because it 
level object and is not added to anything. 
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Constructing the remote bean interface 



Because none of the methods were exposed for the Department bean inter- 
face, they must be exposed in the remote interface for the Department bean, 
which is shown in Listing 7-14. Most of these methods have already been dis- 
cussed. A new one, the addCourse method, is used to add courses to the 
department. To remove courses from the department, you simply call the 
remove method for those particular courses. 



Listing 7-14: Remote Bean Interface for Department 
package com . dummi es . ejb ; 

import Java . rmi .*; 
import Java . uti 1 .*; 
import javax.ejb.*; 
import j avax . nami ng . * ; 

public interface DepartmentRemote extends EJBObject ( 
public DepartmentVO getDepartmentData ( ) 
throws RemoteExcepti on ; 

public void setDepartmentData ( DepartmentVO dept) 
throws RemoteExcepti on ; 

public void addCourse(CourseVO courseData) 

throws Nami ngExcepti on , CreateExcepti on , RemoteExcepti on ; 

public CourseV0[] getAl 1 Courses ( ) throws RemoteExcepti on ; 

) 



Constructing the local home interfaces 

The local interface for the Course bean contains create and f i ndBy meth- 
ods. These methods enable the Department bean to both create and locate 
Course beans. The source code for the Course bean is shown in Listing 7-15 

Listing 7-1 5: Local Home Interface for Course 
package com . dummi es . ejb ; 

import javax.ejb.*; 
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interface CourseLocal Home extends EJBLocal Home 



ic CourseLocal create(CourseVO course) 

throws CreateExcepti on ; 

public CourseLocal fi ndByPrimaryKey ( Integer primaryKey) 

throws Fi nderExcepti on ; 



The Department local bean needs to expose only the f i ndByPri mary Key 
method, because Course never creates Department. The source code for the 
Department bean's local home interface is shown in Listing 7-16. 



Listing 7-16: Local Home Interface for Department 
package com . dummi es . ejb ; 

import javax.ejb.*; 
import Java . uti 1 .*; 

public interface DepartmentLocal Home extends EJBLocal Home { 
public DepartmentLocal fi ndByPrimaryKey ( Integer primaryKey) 
throws Fi nderExcepti on ; 

) 

Constructing the remote home interface 

The only bean that requires a remote home interface is the Department bean. 
This is because the client program directly accesses the Department beans, 
not the Course beans. The Course beans are owned by the Depa rtment 
beans, and all access to the Course beans are through the Department beans. 
The source code for the remote home interface is shown in Listing 7-17. 



Listing 7-17: Remote Home Interface for Department 



package com . dummi es . ejb ; 




import Java . uti 1 . *; 




import Java . rmi .*; 




import javax.ejb.*; 




public interface DepartmentRemoteHome extends 


EJBHome { 


public DepartmentRemote create( DepartmentVO 


Department ) 
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throws CreateExcepti on , RemoteExcepti on ; 



Ic DepartmentRemote fi ndByPrima ryKey( Integer 
pritnaryKey ) 

throws Fi nderExcepti on , RemoteExcepti on ; 

public Collection findAHO 

throws Fi nderExcepti on , RemoteExcepti on ; 

public DepartmentRemote f i ndByName( Java . 1 ang . St ri ng name) 

throws Fi nderExcepti on , RemoteExcepti on ; 



Constructing the abstract bean 
implementation 

Finally, you come to the abstract bean implementation. It's abstract because 
you haven't defined all the required methods of its parent class, which is 
javax.ejb.EntityBean. WebLogic uses the abstract class internally and 
makes it complete by adding the required methods. This is all accomplished 
behind the scenes, so you don't need to be concerned with it. The bean classes 
are simply shortened versions of the bean classes used for the BMP beans. 
Listings 7-18 and 7-19 show the abstract bean classes for the Course bean. 

Listing 7-18: Abstract Bean Class for the Course Bean 

package com . dummi es . ejb ; 

import java.io.Serializable; 
import Java . uti 1 .*; 

import javax.ejb.*; 
import j avax . nami ng . * ; 
import javax.sql .*; 

abstract public class CourseEJB implements EntityBean { 
private Enti tyContext ctx; 

public void setEntityContext(EntityContext ctx) { 
this. ctx = ctx; 



public void unsetEntityContext( ) { 
this. ctx = null; 



public void ejbActivate( ) I) 
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public void ejbPassivate( ) {) 
publ ic void ejbl_oad( ) { ) 
ic void ejbStore( ) { ) 



i c voi d ej bRemove( ) 
throws RemoveExcepti on 



abstract 


publ i 


c 


Integer getld( ) ; 


abstract 


publ i 


c 


void setldC Integer id); 


abstract 


publ i 


c 


Stri ng getName( ) ; 


abstract 


publ i 


c 


void setName(String name); 


abstract 


publ i 


c 


int getCredit( ) ; 


abstract 


publ i 


c 


void setCredi t ( i nt credit); 


abstract 


publ i 


c 


void setDepartment ( Department Local 


abstract 


publ i 


c 


DepartmentLocal getDepartment( ) ; 



public Integer ejbCreate(CourseVO course) 

throws CreateExcepti on 

{ 

setCourseData( course); 
return null; 

) 

public void ejbPostCreate(CourseVO course)!) 

public CourseVO getCourseData ( ) 

( 

CourseVO course = new CourseV0( thi s . getld ( ) ) ; 
course. setNa me (this.getNa me ()); 
course. setCredi t(this.getCredit()); 
return course; 



public void setCourseData (CourseVO course) 
{ 

setName (course. getNa me ()); 
setCredit(course.getCreditO); 

) 

} 



Listing 7-19: Abstract Bean Class for the Department Bean 
package com . dummi es . ejb ; 

import Java . uti 1 .*; 
import javax.ejb.*; 
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ilnport j a vax . nami ng . 



ct public class DepartmentEJB implements EntityBean I 
private Enti tyContext ctx; 

public void setEntityContext(EntityContext ctx) { 
this. ctx = ctx; 

) 

public void unsetEntityContext( ) I 
this. ctx = null; 

) 

public void ejbActivate( ) {) 

public void ejbPassivate( ) {) 

publ ic void ejbl_oad( ) { ) 

public void ejbStoreO {) 

public void ejbRemoveO throws RemoveExcepti on 

{ 

) 



abstract 


publ 


c 


Integer getld( ) ; 




abstract 


publ 


c 


void setld( Integer 


id) ; 


abstract 


publ 


c 


St n" ng getName( ) ; 




abstract 


publ 


c 


void setName(String val ) 


abstract 


publ 


c 


Collection getCourses ( ) ; 



abstract public void setCourses (Col 1 ecti on courses); 

public DepartmentVO getDepartmentData( ) 
{ 

DepartmentVO dept = new DepartmentVCKthis .getldC ) ) ; 
dept . set Name ( thi s . get Name ( ) ) ; 
return dept; 



public void setDepartmentData(DepartmentVO dept) 
( 

setName( dept . get Name ( ) ) ; 



public Integer ejbCreate(DepartmentVO dept) 

throws CreateExcepti on 

{ 

setDepartmentData(dept) ; 
return null; 



public void ejbPostCreate(DepartmentVO dept) 
throws CreateExcepti on 
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ic CourseV0[] getAl 1 Courses ( ) 



Collection courses = getCourses ( ) ; 
CourseV0[] courseArray = new CourseVO [courses .size( )]: 
Iterator courselterator = courses . iterator( ) ; 
for ( int 1=0; courselterator . hasNext () ; i++ ) ( 
CourseLocal course = (CourseLocal ) 

courselterator . next ( ) ; 
courseArray [i ] = course . getCourseData () ; 



return courseArray; 

} 



public void addCourse(CourseVO courseData) throws 
NamingException, CreateException 

{ 

Context ctx = new Ini ti al Context () ; 
CourseLocal Home courseHome = (CourseLocal Home ) 

ctx. lookupC'cmp. Course") ; 
CourseLocal course = courseHome. create(courseData ) ; 
getCoursesO.add(course); 

) 



As you can see in Listings 7-18 and 7-19, the abstract bean classes are imple- 
mented as abstract Java classes. WebLogic extends these classes and adds 
the appropriate methods to access the objects. These methods perform the 
same functions as the BMP bean. 



Constructing the bean configuration files 

CMP beans use a total of three configuration files: the e j b - j a r . xml and 
webl ogi c-e jb- j ar . xml files as were used by BMP beans and a database 
mapping file called weblogic-rdbms-jar.xml.I start with the e jb- j ar . xml 
file, which is shown in Listing 7-20. 



Listing 7-20: J2EE Standard Bean Configuration File 

<?xml versi on=" 1 . 0" ?> 
<!D0CTYPE ejb-jar PUBLIC 

'-//Sun Microsystems, Inc. //DTD Enterprise JavaBeans 2.0//EN' 

'http://java.sun. com/ j2ee/dtd/ejb- jar_2_0 . dtd ' > 

<ejb-jar> 

<enterpri se-beans> 
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<enti ty> 

<e jb-name>DepartmentEJB</ej b-name> 
khomeXom . dummi es . ejb . Depa rtmentRemoteHome</ home) 
<remote>com.dummies.ejb. Dep a rtmentRemote</ remote) 
<local-home>com.dummies.ejb.Departmentl_ocal Home</l ocal 
home> 

<1 ocal Xom . dummi es . ejb . Depa rtment Local </l ocal > 

<e jb-cl ass>com . dummi es . ejb . Depa rtment E J B</e jb-cl ass> 

<persistence-type>Container</persistence-type> 

<prim- key-cl ass>java.lang. I nteger</prim-key-cl ass> 

<reentrant>False</reentrant> 

<cmp-version>2.x</cmp-version> 

<a bst r a ct - schema -name>Depa rtment Sen ema< /abstract - 

schema -name> 
<cmp-f i el d> 

<field-name>id</field-name> 
</cmp-f iel d> 
<cmp-f i el d> 

<field-name>name</field-name> 
</cmp-f iel d> 

<primkey-f i el d>i d</primkey-f i el d> 
<query> 

<query-method> 

<method-name>findByName</method-name> 
<method-pa rams> 

<method-param>java .lang.String</method-param> 
</method-params> 
</query-method> 

<ejb-ql><! [CDATA[ SELECT OBJECT(d) FROM 

Depa rtmentSchema AS d WHERE d.name = ?l]]X/ejb- 
ql> 
</query> 
<query> 

<query-method> 

<method-name>findAll</method-name> 
<method-params/> 
</query-method> 

<ejb-ql><! [CDATA[ SELECT OBJECT(d) FROM 
DepartmentSchema AS d]]X/ejb-ql> 
</query> 
</enti ty> 
<enti ty> 

<ejb-name>CourseEJB</ejb-name> 

<local-home>com.dummies.ejb.CourseLocal Home</l ocal - 
home) 

<1 ocal > com . dummi es. ejb. Course LocaK/local) 

<e jb-cl ass>com . dummi es. ejb. Course EJB</ejb-class> 

<persi stence-type>Conta i ner</persi stence-type> 

<p rim- key-cl ass>java.lang.I nteger</prim - key-cl ass> 

<reentrant>False</reentrant> 
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<cmp- versi on>2 . x</cmp- versi on> 

<a bstr act -schema -name>CourseSchema< /abstract -schema - 

name> 
,<cmp-f i el d> 

<field-name>id</field-name> 
</cmp-f iel d> 
<cmp-f i el d> 

<f i el d-name>name</f i el d-name> 
</cmp-f iel d> 
<cmp-f i el d> 

<f i el d-name>credi t</field-name> 
</cmp-f iel d> 

<primkey-f i el d>i d</primkey-f i el d> 
</enti ty> 
</enterprise-beans> 
<rel ati onshi ps> 
<ejb-rel ati on> 

<ejb-relati on-name>Department-Course</ejb-rel ati on - 
name) 

<ejb-relationship-role> 

<ejb-relationship-role-name> 

Department -Has -Courses 
</ejb-relationship-role-name> 
<mul ti pi i ci ty>one</mul ti pi i ci ty> 
<rel ati onshi p-role-source> 

<e jb-name>DepartmentEJB</ej b-name> 
</rel ati onshi p-role-source> 
<cmr-f i el d> 

<cmr-field-name>courses</cmr-field-name> 
<cmr-field-type>java.util.Collection</cmr-field- 
type> 
</cmr-f i el d> 
</ejb-rel ati onshi p-role> 
<ejb-relationship-role> 

<ejb-relationship-role-name> 

Course -Has -Department 
</ejb-relationship-role-name> 
<mul ti pi i ci ty>many</mul ti pi i ci ty> 
<cascade-del ete/> 
<rel ati onshi p-role-source> 

<ejb-name>CourseEJB</ejb-name> 
</rel ati onshi p-role-source> 
<cmr-field> 

<cmr-f i el d-name>department</cmr-f i el d-name> 
</cmr-f i el d> 
</ejb-rel ati onshi p-role> 
</ejb-rel ati on> 
</rel ati onshi ps> 
<assembly-descriptor> 
<container-transaction> 



(continued) 
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<method> 

<ejb-name> Depart me ntEJB</ejb-name> 
<method-name>*</method-name> 
</method> 

<trans-attribute>Required</trans-attribute> 
</container-transaction> 
<container-transaction> 
<method> 

<ejb-name>CourseEJB</ejb-name> 
<me t h od - n ame >*< / me t h o d - n a me > 
</method> 

<trans-attribute>Required</trans-attribute> 
</container-transaction> 
</assembly-descriptor> 
</ejb-jar> 



Many of these entries are the same as those in the BMP version of the file. 
The first difference to note is the cmp-f i el d tags, which specify the property 
names for each bean. These fields are not database fields, but rather fields 



mapped to the database. The cmp 


-field tag; 


s contain only the field names: 


<cmp-field> 

<f ield-name>. . 
</cmp-f i el d> 


.field nam> 


2. . .</f ield-name> 




Queries are also included that show WebLogic how to provide information to 
the f i ndBy methods in the home classes. This allows the f i ndBy methods to 
construct SQL queries to find the appropriate record. The following query 
shows how you can implement f i ndByName for the Department bean: 



<query> 

<query-method> 

<method-name>f i ndBy Name< /met hod- name> 
<method-params> 

<method-param>java.lang.String</method-param> 
</method-params> 
</query-method> 

<ejb-ql><! [CDATA[ SELECT OBJECT(d) FROM Depa rtmentSchema AS 
d WHERE d.name = ?l]]X/ejb-ql> 

</query> 



You can specify multiple parameters in the ejb-ql tag. These will be filled in 
with the value that you're searching on. For example, the preceding code is 
filling in the ? 1 parameter to specify a name that's being searched for. The 
ejbrelationshi prole tag specifies how the tables relate to each other. 
The mul ti pi i ci ty tag specifies whether the relationship is to one object or 
multiple objects. If the cascade-del ete tag is specified, child objects are 
deleted when the parent object is deleted. 
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The WebLogic-specific configuration file, which is shown in Listing 7-21, con- 
tains additional information for CMP beans. 
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-21: WebLogic Bean Configuration File 



<?xml version = "l .0"?> 

<!D0CTYPE weblogic-ejb-jar PUBLIC '-//BEA Systems, Inc. //DTD 
WebLogic 6.0.0 EJB//EN ' 

' http : //www .bea.com/servers/wls600/dtd/ we blogic- 
ejb-jar.dtd' > 

<webl ogi c-ejb-jar> 

<weblogic-enterprise-bean> 

<ejb-name>DepartmentEJB</ejb-name> 
<enti ty-descri ptor> 
<persi stence> 
<persistence-type> 

<type- i denti f i er>WebLogi c_CMP_RDBMS</type-i denti f i er> 
<type-version>6.0</type-version> 

<type-storage>META- INF/webl ogi c-cmp-rdbms- j ar . xmK/type- 
storage> 
</persistence-type> 
<persi stence-use> 

<type- i denti f i er>WebLogi c_CMP_RDBMS</type-i denti f i er> 
<type-version>6.0</type-version> 
</persistence-use> 
</persi stence> 
</enti ty-descri ptor> 
<jndi-name>cmp. Department</jndi -name> 

<1 ocal - j ndi -name>cmp . Department- Local </local-jndi-name> 
</weblogic-enterprise-bean> 

<weblogic-enterprise-bean> 

<ejb-name>CourseEJB</ejb-name> 
<enti ty-descri ptor> 
<persi stence> 
<persi stence-type> 

<type- i denti f i er>WebLogi c_CMP_RDBMS</type-i denti f i er> 
<type-version>6.0</type-version> 

<type- storage >M ETA- INF/webl ogi c-cmp-rdbms -jar. xml</ type- 
storage) 
</persistence-type> 
<persi stence-use> 

<type- i denti f i er>WebLogi c_CMP_RDBMS</type-i denti f i er> 
<type-version>6.0</type-version> 
</persi stence-use> 
</persi stence> 
</entity-descriptor> 

<1 ocal -j ndi -name>cmp .Course</l ocal - j ndi -name > 
</weblogic-enterprise-bean> 



</webl ogic-ejb-jar> 
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You need to configure the persistence-type tags . Inside these tags , leave 
the type-i denti f i er and type versi on tags as they are. You need to set 
-storage tag to the path of your mapping file. Mapping files are dis- 
xt. 



The last configuration file is the database mapping file, which is shown in 
Listing 7-22. This file specifies the table names and maps the bean properties 
to the correct fields. 



Listing 7-22: Database Mapping for WebLogic 

<!D0CTYPE weblogic-rdbms-jar PUBLIC 

'-//BEA Systems, Inc. //DTD WebLogic 6.0.0 EJB RDBMS 

Persi stence/ /EN ' 
' http : //www .bea.com/servers/wl s600/dtd/webl ogi c-rdbms20- 

persistence-600.dtd'> 
<webl ogic-rdbms-jar> 
<weblogic-rdbms-bean> 

<ejb-name>DepartmentEJB</ejb-name> 

<dat a -source- name) jd be /School Da ta Sour ceTX</data- source - 
name) 

<tabl e-name)t_department</tabl e-name> 
<f i el d-map> 

<cmp-f i eld>id</cmp-field> 
<dbms-col umn>f_id</dbms-col umn> 
</f i el d-map> 
<f i el d-map> 

<cmp-f i el d>name</cmp-f i el d> 
<dbms-col umn>f_name</dbms-col umn> 
</f i el d-map> 

</webl ogic-rdbms-bean> 

<webl ogi c- rdbms-bean> 

<ejb-name>CourseEJB</ejb-name> 

<data -source -name>jdbc/School Data SourceTX</data -source - 
name> 

<tabl e-name>t_course</tabl e-name> 
<f i el d-map> 

<cmp-f i eld>id</cmp-field> 

<dbms-col umn>f_id</dbms-col umn> 
</f i el d-map> 
<f i el d-map> 

<cmp-field>name</cmp-field> 

<dbms-col umn>f_name</dbms-col umn> 
</f i el d-map> 
<f i el d-map> 

<cmp-f i el d>credi t</cmp-f i el d> 

<dbms-col umn>f_credit</dbms-col umn> 
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</f i el d-map> 

uebl ogic-rdbms-bean> 



elol ogic-rdbms-relation> 

<rel ati on-name>Department-Course</rel ation-name> 
<weblogic-relationship-role> 

<relationship-role-name>Course-Has- 
Department</rel ationship-role-name> 
<col umn-map> 

<f orei gn -key -col umn>f_department_i d</foreign-key- 
col umn> 

<key-col umn>f_id</key-col umn> 
</col umn-map> 
</weblogic-relationship-role> 
</weblogic-rdbms-relation> 
</weblogic-rdbms-jar> 



Tables are defined inside webl ogi c rdms bean tags. The tag contains the 
following information: 











<tabl e-name> . 


. . the name of the tabl e 


; . . . </tabl e-name> 





<f i el d-map> 

<cmp-fiel d>. . .property name of first f i el d . . . </cmp-f i el d> 
<dbms -col umn> ... database field name . . . </dbms-col umn> 

</f i el d-map> 

<f i el d-map> 

... the second field... 

</f i el d-map> 



By creating one f i e 1 d - m a p tag for each field in your table, you can map the 
entire table. For every foreign key, you must also create aweblogicrdbms- 
rel ati on tag. This specifies the foreign key relationship. As you can see, 
webl ogi c-rdbms- relation specifies the foreign key using the f orei gn- 
key col umn tag and maps it to the primary key of that table. 



Compilinq a CMP Bean 

You compile a CMP bean in the same way you compile a BMP bean. Listing 7-23 
is a script that uses the correct names for the CMP bean you just created. 



Listing 7-23: Script to Compile the CMP Bean 

©echo off 

@rem Set this to the location of your JDK installation 

(continued) 
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t JDK_H0ME=C:\j2sdkl.4.1_01 




'et this to the location of your J2EE JAR file 
set CLASSPATH=C: \j2sdkeel.4\l ib\j2ee. jar 



@rem Set this to the location that the class files will be 

stored 
set CLASSES=.\CLASSES 



@rem setup the directory structure 

rmdir /q /s %CLASSES% 

mkdir %CLASSES% 

mkdir %CLASSES%\META-INF 



@rem compile the classes 

"%JDK_H0ME%" \bi n\ javac .\src\com\dummies\ejb\*. java - 
classpath %CLASSPATH% -d %CLASSES% 

@rem copy the config files 

xcopy /y .\src\META-INF\*.* %CLASSES%\META-INF\ 

@rem JAR it up 
cd %CLASSES% 

"%JDK_HOMEr\bin\jar -cvf . . \CMPBean . ja r *.* 
cd . . 



CMP and BMP beans enable you to make data persistent, so you can isolate 
your database code to the beans and keep it away from other beans dedi- 
cated to business processing logic. This isolation means that you have fewer 
places to change if you alter the structure of your database. 
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In This Chapter 

Getting your directories in order 

Creating deployment descriptors with tools or by hand 

Packaging an enterprise application 

Deploying an enterprise application 

The term enterprise application is used by a variety of products. For 
WebLogic and J2EE, an enterprise application is comprised of one or 
more of the following technologies: 

If Web application 
Enterprise JavaBeans 
V Client application 

If you're already creating applications that use these components, you may be 
wondering why you'd need an enterprise application. Well, enterprise applica- 
tions provide a way to package all these components in a single archive. The 
main advantage is that you would then have one file to manage and deploy. If 
you're still working on your application, however, you'll find it easier to work 
with the expanded version of your application, not one packaged into a single 
enterprise application file. 

Because it's easier to develop an application using individual files and direc- 
tories, compress your application into an enterprise archive file only after 
you complete the development stage. 

In this chapter, you discover how to create an enterprise application. Rather 
than showing you how to create the components that make up an enterprise 
application, however, I show you how to connect these pieces in an enterprise 
application. To create the components of an enterprise application, refer to 
Chapter 5 for details on web applications and Chapters 6 and 7 for information 
on EJBs and client applications. 




Part II: Understanding WebLogic Components 



Creating an enterprise application consists of four major steps: 



DBocte 



nge the components that make up the enterprise application into 
roper directory structure. 



2. Create your deployment descriptors. 

3. Compress the entire structure into a JAR file. 

4. Deploy your enterprise application. 

You go through each of these steps in this chapter. 



Orqanizinq \lour directories 

The first step in creating an enterprise application is to organize your directo- 
ries. You must move the files that make up your EJBs into a single directory 
structure. If you've been developing your application's individual compo- 
nents, you're probably close to finishing this step. 



The structure of the WebLogic directory 

Understanding the WebLogic directory structure is important when creating 
an enterprise application because it helps you know where to place specific 
file types. When you first create your WebLogic domain, as discussed in 
Chapter 4, you specify a root directory for it. This directory is usually a sub- 
directory of c : \bea\user_projects\. 

The web applications directory (described in detail in Chapter 5) is stored in 
a subdirectory named appl i cations, which is in your domain directory. 
WebLogic provides you with at least one web application, which is named 

Def aul tWebApp. 

In this chapter, I assume that you're using a web application named MyWebApp. 
If you're using the default web application, the instructions remain the same 
except you use Def a ul tWebApp as the name of your web application. 

The root directory of your web application forms the base from which you 
package your enterprise application. For example, if you created a domain 
named my doma i n and are using the default web application, this root is 

C : \bea\user_projects\mydomai n\appl ications\Defaul tWebApp 

If your web application is named MyWebApp, the root is 

C : \bea\user_projects\mydomai n\appl i cat i on s\ MyWebApp 
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These are Windows paths. UNIX users have a /user_projects subdirectory 
to the directory that holds WebLogic. 

directory 

Everything that you store in the root directory of your WebLogic server can 
be accessed by the user. Consider the example of WebLogic Server installed 
in the following directory: 

C : \bea\user_projects\mydomai n\appl i cati ons\MyWebApp 

Your root directory is My Web Ap p. Every file that you place in this directory is 
exposed to the Internet. For example, if you stored the myfile.asp file in 
My WebApp, you could see this file by accessing the following page: 

http : //l ocal host : 7 001 /my f i 1 e . asp 

The same is true of directories that you place in the Def aul tWebApp direc- 
tory. For example, if you create a directory named images and place into it a 
file named photo.jpg, you could see this file by accessing the following URL: 

http : //local host: 7001 /images/ photo. jpg 

However, one directory is not exposed to the Internet: WEB - IN F, which is in 
your root directory. This directory holds configuration information and other 
important subdirectories used by WebLogic. 

Because every other directory in the root directory is exposed to the 
Internet, be careful about what you place there. Configuration and other sen- 
sitive information should be kept in the WE B - 1 N F directory so that the infor- 
mation can't be downloaded by a malicious user. 

Now that you've seen the purpose of the root and W EB - 1 N F directories, you 
can take a look at the directories inside the WE B - 1 N F directory. 

The WEB-lNF/ctasses directory 

This is the directory where you place the .class files, which are used to imple- 
ment servlets. Any .class file in this directory is automatically available to 
WebLogic. 

When creating an enterprise application, make sure that your individual 
.class files and servlets are in the WEB-INF/classes directory. This ensures 
that they're packaged to the correct location and that WebLogic can find 
them when you deploy your enterprise web application. 



O/ks 
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You can't just place the .class files in this directory. Like any Java .class file, 
they must be placed in a subdirectory that corresponds to their package. For 
: your .class file is in the com . dummi es . e j b package, you have to 
com/dummi es/ej b directory structure under your cl asses direc- 
tory. You then place your .class file in the e j b subdirectory. 



mey must a 



The WEB4NF/tib directory 

Your web application may use a variety of JAR files to perform its operations. 
JAR files contain class libraries that give your program additional functional- 
ity. These JAR files may have been created by you or by a third party. 
Regardless of their source, JAR files must be placed in the WEB-INF/lib 
directory if WebLogic is to make use of them. 

One common use for the WEB-INF/lib directory is to store the JAR files 
associated with tag libraries. A tag library is a class library contained in a JAR 
file. Including the tag library in your application gives you access to addi- 
tional tags that you can use in your JSP pages. 



The WEB4NF/ttds directory 

Tag libraries require additional setup beyond just placing their JAR files into 
the 1 i b directory. Tag libraries also require tag library descriptor (TLD) files. 
These TLD files are placed in the W E B - 1 N F / 1 1 d s directory. 



Examining the directory structure 

Now that you've seen the directories that make up an enterprise application, 
it's time to see how the files in those directories are laid out. Table 8-1 shows 
some of the files in a typical enterprise application. This application has two 
primary areas: the main area of the application, which stores its JSP files in 
the root, and an administration area. The administration area would likely be 
secured with a password by using logic contained in the JSP pages. This 
application also makes use of one servlet and a tag library. 



Table 8-1 File Structure of a Typical Web Application 


File or Directory 


What It Is 


MyWebApp/ 


The root directory of your web application 


MyWebApp/i ndex . jsp 


The index for your web application 


MyWebApp/mai n .jsp 


A JSP page that's part of your web application 


MyWebApp/admi n 


A programmer-defined directory containing the 




JSP pages needed for the administration section 




of your web application 
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File or Directory 


What It Is 


"\ mWffkApp/admi n/ 


The index page displayed for the administration 


J ri\dO . j s p 


section 


DefaultWebApp/ 


An HTML file that's part of your web application 


admi n/i nf o . html 





MyWebApp/ images A programmer-defined directory that contains the 

image files for your web application 

MyWebApp/images/ Agraphicsfile used byyourweb application 

logo.gif 

MyWebApp /WEB - INF A directory that is not visible to the Internet and that 

holds configuration files and other system directories 



MyWebApp/WEB- INF/ J2EE standard configuration information foryour 
web.xml web application 



MyWebApp/WEB- INF/ 
webl ogi c . xml 


WebLogic-specific configuration information for 
your web application 


MyWebApp/1 i b 


A directory that contains the JAR files for 
application 


your 


MyWebApp/1 i b/mytag 
1 i b . j a r 


A JAR file needed 


by your web applicatioi 


i 


MyWebApp/cl asses 


A directory that contains the .class files for your 
application 



MyWebApp/cl asses/ A class file needed byyourweb application 

com/dummi es/servl et/ 
myservl et .class 



MyWebApp/tl ds A directory that contains the tag library 

descriptors for your web application 

MyWebApp/tl ds/my Atag library definition file for your web application 

tags . tl d 



Note that throughout the folders used by this web application are numerous 
configuration files, which are called descriptors. In the next section, you find 
out the part that descriptors play in an enterprise application. 



Creating Deployment Descriptors 



The second step in creating an enterprise application is perhaps your biggest 
task: creating your deployment descriptors. Deployment descriptors are XML 
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files that contain configuration information about your enterprise application 
and its components. This section begins with an introduction to the individ- 
yment descriptors that WebLogic uses. 



d Books 

Understanding deployment descriptors 



Deployment descriptors are not unique to WebLogic; they're a J2EE concept. 
However, WebLogic contains features that extend the capabilities of J2EE. You 
can't put non-compliant J2EE information in a J2EE deployment descriptor, so 
WebLogic introduced a special XML file that contains WebLogic-specific infor- 
mation. Because of this, all deployment descriptor files come in pairs: the J2EE 
deployment descriptors and the WebLogic deployment descriptors. Table 8-2 
summarizes these deployment descriptors. 



Table 8-2 


J2EE and WebLogic Deployment Descriptors 


Purpose 


J2EE Descriptor 


WebLogic Descrip, 


for 


Client applications 


application-client.xml 


client-application. runtime. xml 


Enterprise 
applications 


../META-INF/ 
application.xml 


META-INF/application.xml 






Enterprise JavaBeans 


../M ETA- II 


\IF/ejb-jar.xml 


../META-INF/webloi 
ejb-jar.xml, .,/META 
INF/weblogic-cmp- 


gic- 

rdbns.xml 


Resource adaptors 


../META-INF/ra.xml 


META-INF/weblogi 


c-ra.xml 


Web applications 


../WEB-INF/web.xml 


WEB-INF/weblogic 


.xml 



When creating descriptors, you have two choices: You can use utilities pro- 
vided with WebLogic to create your descriptors automatically or you can 
create the descriptors by hand. 

Even if you choose to create descriptors automatically, you still have to do 
some configuration. When you use a tool to generate your descriptors, that 
tool examines your files and directory structure and makes its best guess as 
to how the deployment descriptor should be constructed. You can't entirely 
escape the process of creating descriptor files because the tool may not 
always properly determine every unique aspect of your application. It would 
be impossible for BEA to create a tool that can handle every conceivable way 
that an enterprise application could be set up. 
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Although automatic generators often do not create perfect deployment 
descriptors, they do generate descriptors that are a closer match to your 
icriptors than any sort of template descriptor. Because of this, you 
se the descriptor generators to generate the first version of your 
deployment descriptors. 
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Creating descriptors using toots 

WebLogic includes several tools that you can use to automatically generate 
descriptors for your enterprise application. These tools are implemented as 
command-line Java utilities. Before you can use these utilities, however, you 
must make sure that CLASSPATH is set correctly. 

Setting CLASSPATH 

The utility classes are located in the weblogic.jar file, and you must make this 
file part of CLASSPATH. You can do this by issuing the following command to 
your command prompt: 

set CLASSPATH= 

%CLASSPATH% ; C : \bea\webl ogic81\server\lib\weblogic.jar 

This adds the weblogic.jar file to CLASSPATH for the current command 
prompt. If you close the command-prompt window, you must reissue the pre- 
ceding command to use the utility classes again. 

If you find that you're using the descriptor generation utilities frequently, you 
may want to permanently add weblogic.jar to your system C LASSPATH. To do 
so, modify the CLASSPATH environmental variable on your system. The instruc- 
tions for doing this vary depending on your operating system, so refer to your 
operating system instructions for more information. 

Invoking the descriptor generation utilities 

WebLogic has four descriptor generation utilities, as shown in Table 8-3. 
Which utility you should use depends on the type of descriptor that you want 
to generate. 

You invoke these utilities just as you would any other Java utility: by specify- 
ing the main class. For example, to generate the web.xml and weblog.xml 
descriptors for the web application stored at the following location: 
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Table 8-3 



Enterprise ap 



Deployment Descriptor Utilities 



Main Class 



rise application 



weblogic.ant.taskdefs.ear.DDInit 



Enterprise JavaBeans (EJB) 1.0 



weblogic.ant.taskdefs.ejb.DDInit 



Enterprise JavaBeans (EJB) 2.0 



weblogic.ant.taskdefs.ejb20.DDInit 



Web application 



weblogic.ant.taskdefs.war.DDInit 



C : \bea\user_projects\mydomai n\appl i cati ons\MyWebApp 
you would issue the following command: 

Java webl ogi c . ant . taskdef s .war . DDIni t c:\bea\user_projects 
\mydomai n\appl i cati ons\MyWebApp 

Although this command spans more than one line, it must be entered as one 
command. This command generates the web.xml and weblogic.xml files for 
MyWebApp and places them in the WEB - 1 N F directory. 

Creating descriptors manually 

In this section, you create by hand the application.xml file, the J2EE enterprise 
descriptor for an enterprise application. You may include the weblogic.xml 
descriptor as well. Both files are covered in this section. 

The J2EE enterprise descriptor 

The J2EE enterprise descriptor is named application.xml. An example appli- 
cation.xml file is shown in Listing 8-1. 



Listing 8-1: J2EE Enterprise Descriptor 



<?xml versi on = " 1 . 0" encoding="UTF-8"?> 
<!D0CTYPE application PUBLIC 

'-//Sun Microsystems, Inc. //DTD J2EE Application 1.3//EN' 
' http : // Java. sun. com/dtd/appli cati on_l_3 . dtd ' > 

<appl i cati on> 

<di spl ay -name) Home Met hods ejb20</display-name> 
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<descri pti on>HomeMethods ej b20</descri pti on> 
ul e> 

b>ejb20_homemethods .jar</ejb> 
dule> 




</appl i cati on> 

The main purposes of the application.xml file are to identify the EJBs used 
with your web application and to tie together all the components that make 
up the application. Table 8-4 lists the components in application.xml. 



Table 8-4 XML Elements for application.xml 



Element 


What It Does 


appl i cati on 


Contains the other elements described in this table. This is 
the root element of the application deployment descriptor. 


i con 


Specifies the locations of small and large images that 
represent the application in a GUI tool. Currently, 
WebLogic Server doesn't use this element, so its inclusion 
is optional. 




smal 1 -i con 


Specifies the location for a small (16x16 pixel) .gif or Jpg 
image that represents the application in a GUI tool. 
Currently, WebLogic Server doesn't use this element, so its 
inclusion is optional. 


1 arge-i con 


Specifies the location for a large (32x32 pixel) .gif or .jpg 
image that represents the application in a GUI tool. 
Currently, WebLogic Server doesn't use this element, so its 
inclusion is optional. 


di spl ay -name 


Describes the name of the application displayed by 
GUI tools. 


descri pti on 


Describes the application displayed by GUI tools. 


modul e 


This element specifies EJBs, servlets, and other compo- 
nents. One modul e element exists for every module in 
WebLogic. 


alt-dd 


Specifies an optional URI to the post-assembly version of 
the deployment descriptor file for a particular J2EE module. 
The URI must specify the full path name of the deployment 
descriptor file relative to the application's root directory. If 
you do not specify al t-dd, the deployer must read the 
deployment descriptor from the default location and file 
name required by the respective component specification. 


(continued) 
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■ 


What It Does 




connector 


Specifies the URI of a resource adapter (connector) 
archive file, relative to the top level of the application 
package. 


ejb 


Defines an EJB module in the application file. Contains the 
path to an EJB JAR file in the application. 


web-uri 


Defines the location of a web module in the application.xml 
file. This is the name of the WAR file. 


context- root 


Specifies the context root for the web application. 


descri pti on 


Describes the security role. 




rol e-name 


Defines the name of a security role or principal used for 
authorization in the application. 



As you can see from Table 8-4, you can specify security information as well as 
information about the components of the enterprise application. Security is 
discussed in Chapter 18. 

The WebLogiC'Specific descriptor 

The WebLogic-specific enterprise descriptor is named weblogic.xml. This 
descriptor allows you to specify security settings that are not part of the J2EE 
descriptor. You can use this descriptor to create security roles that govern the 
abilities of users. An example weblogic.xml file is shown in Listing 8-2. 



Listing 8-2: WebLogic Enterprise Descriptor 

<?xml versi on=" 1 . 0" encoding="UTF-8"?> 

<!D0CTYPE weblogic-web-app PUBLIC 

"-//BEA Systems, Inc. //DTD Web Application 7.0//EN" 

" http : //www . bea. com /servers/wls700/dtd/ we blogic700- we b- 

jar.dtd" > 
<webl ogi c-web-app> 

<security-role-assignment> 

<role-name>GoodRole</role-name> 

<principal-name>larry</principal-name> 

<principal-name>moe</principal-name> 

</security-role-assignment> 

</weblogic-web-app> 

Many of these elements are related to security, a topic discussed in Chapter 18. 
Table 8-5 offers a brief description of the WebLogic elements. 
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Table 8-5 


XML Elements for weblogicxml 




What It Does 


web Togi c-web-app 


Contains the other elements described in this table. 
This is the root element of the WebLogic deployment 
descriptor. 


descri pti on 


Describes this enterprise application. 


webl ogi c-versi on 


Specifies the version of WebLogic for which this file 
was designed. 



security-role- Specifiesa security role assignmentthat can be used 

assi gnment in the J2EE enterprise application descriptor. 



ref erence- 
descri ptor 


Matches resource-ref elements in the 
descriptor to JNDI names. 


web.xml 


sessi on-descri ptor 


Determines how WebLogic configures eacl 


i session. 


jsp-descri ptor 


Determines how WebLogic handles JSP files. 


auth -f i 1 ter 


Specifies the full class name of a servlet that handles 
authentication. 


charset-params 


Determines charset mappings for GETs and POSTs. 





Packaging \lour Enterprise Application 

The third step in creating an enterprise application is to package, or archive, 
your enterprise application. The enterprise application is stored in a JAR file, 
which is a special archive file used by Java. The file format of a JAR file is the 
same as the format for a ZIP archive. JAR files usually end with the .jar exten- 
sion, but the extension can be changed to anything you want. 

Although enterprise applications are stored as JAR files, they use the .ear 
extension, not the .jar extension. In this section, you find out how to convert 
your enterprise application's directory structure to an EAR file. 

Follow these steps to package your enterprise application: 

1. Create a temporary directory anywhere on your hard drive. 

You'll use this directory to stage the directories and files in your enter- 
prise application. 

2. Copy all web archives (WAR files) and EJB archives (JAR files) to the 
staging directory. 
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3. Create aMETAINF subdirectory in the staging directory, 
up your shell environment. 



u're using Windows, execute the setenv . cmd command, which is 
inThe "WebLogi c Home" \bi n\setenv . cmd directory. If you're using 
UNIX, execute the setenv . sh command, which is in the "WebLogi c 
Home" / bi n /setenv . sh directory. For Windows or UNIX, replace 
"WebLogic Home" with the directory that you installed WebLogic to. 

5. Create the application.xml deployment descriptor file and place it in 
the M ETA I N F directory. 

For more information on this step, see the preceding section. 

6. Optionally create the weblogic.xml file and place it in the M ETA INF 
directory. 

For more information on this step, see the preceding section. 

7. Create the Enterprise archive (EAR file) for the application, using the 
following jar command: 

jar cvf appl i cati on. ear C stagingdir 

where appl i cati on is the name of your application and stagi ng is 
your staging directory. 

Now that you've created an EAR file, it's time to deploy it. 

JAR, WAR, and EAR files have the same format as a ZIP file. Therefore, you 
can simply copy each to a new file — renaming it as .zip — and then use 
WinZip to view the contents of the file. This is a fast way to look inside the 
archive. 



Deploying \lour Enterprise Application 

The fourth step in creating an enterprise application is to deploy it to 
WebLogic Server. 

After you've packaged your web application to an EAR file, you deploy it as 
many times as needed. This provides a convenient way to distribute your 
enterprise application to any number of servers. 

Follow these steps to deploy an enterprise application: 

1. Ensure that WebLogic Server is running. 

2. Log on to Administration Console at http : //l ocal host : 7001/ 
consol e. 
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3. In the left pane, click the Deployments folder, and then click the 
Applications folder. 



screen shown in Figure 8-1 appears. 
Click the Deploy a new Application link. 

The screen shown in Figure 8-2 appears. 



5. Click the upload your filefs) link, type the name of the EAR file that 
you'll be uploading to the server, and then click the Upload button. 

6. Click the radio button that appears next to your newly uploaded EAR 
file, and then click Continue. 

7. Type a name for your application. 

8. Click the Deploy button. 

The screen shown in Figure 8-3 appears. After a few moments, the 
deployed status will go to the value of compl eted. 

Your enterprise application is now deployed and ready for use. Now that 
you've created an enterprise application, you're ready to find out about some 
of the services that WebLogic provides. That's the topic of the next part of 
the book. 
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contained in a J2EE application can be deployed to one or more target servers or 
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When one or more applications have been configured for deployment in the current 
WebLogic Server domain, this Applications page displays key information about the EAR 
files or exploded EAR directories. To configure an application for deployment, click the 
Deploy a new Application link. 
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This page allows you to view the deployment status of each module in the 
application, and to stop or redeploy individual modules. You may also choose to 
stop and redeploy all modules within the application using the buttons at the 
bottom of the page. (To configure additional deployment targets for this 
application, click the Targets tab.) 
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IM/eb applications are programs that run on a web 
▼ ▼ server and are usually accessed by humans. A web 
service is similar to a web application in that it can run 
from a web server. However, web services are usually 
accessed by computer programs, not humans. Additionally, 
a web service can run over e-mail as well as the web. In this 
part, you create a simple web service in WebLogic. 

After you create a web service, you'll want to access it, 
so your next task is constructing a client program to do 
just that. 

Finally, you use Resource Workshop to create a web ser- 
vice. Resource Workshop uses a GUI similar to Visual 
Basic, so you can design your web service graphically. 
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In This Chapter 

Defining what your web service will do 

Building the backend component 

Building synchronous and asynchronous web services 

Packaging web services 

Deploying web services 




mM/eh services have received a lot of media attention lately. But what 
WW exactly is a web service? A web service is a remote procedure avail- 
able to clients through TCP/IP, typically using HTTP or SMTP as the transport 
and XML for encoding. The web service is described using standard XML 
notation called a service description. A web service fulfills a single task or a 
set of tasks. 

All details of the web service are hidden from the user, and the service is 
both hardware and software independent. This encourages software develop- 
ers to build applications consisting of small, individual services, which can 
then be used alone or in groups to perform even more complex tasks. 

You can create a web service in two ways: manually, through the creation of 
Java source and configuration files, or using a GUI system called WebLogic 
Workshop. In this chapter, you create a web service manually. For more on 
WebLogic Workshop, see Chapter 11. 

WebLogic services are built on the Simple Object Access Protocol (SOAP), 
a standard protocol upon which XML messages are exchanged between web 
services and their clients. Generally, WebLogic deals with the details of the 
SOAP protocol, freeing you to focus on building your web service. However, 
if you're interested in knowing more about SOAP, go to the site of the World 
Wide Web consortium, the group that maintains the SOAP standard, at 
http://www.w3.org/TR/S0AP/. 
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Understanding SOAP 



rased, lightweight protocol 
that's used for information exchange. This pro- 
tocol works in both decentralized and distrib- 
uted environments. SOAP is decentralized in 
that the provider of a SOAP service and the con- 
sumer program can be run on two different 
computers. SOAP is distributed in that many dif- 
ferent computers can provide the same SOAP 
service, which allows these computers to bal- 
ance the load of requests to achieve maximum 
performance. 

SOAP consists of three main parts: 

V SOAP envelope. The SOAP envelope por- 
tion of the message describes what's in a 
message and how to process it. It contains 
a target address specifying the server that 
the SOAP message is targeted to and a 
return address specifying where the server 
should send its response. The encoding 
rules are specified by the XML attribute 
SOAP-ENV:Envelope. 

V Encoding rules. For expressing the applica- 
tion's data types. Every SOAP message con- 
tains the rules used to encode it. These 
rules specify what version of SOAP was 
used and how different components of the 
SOAP message are represented. The 
encoding rules are specified by the XML 
attribute SOAP- EN V : encodi ngStyl e. 

f* Method call. When a SOAP message is 
sent, part of the message specifies the 



methods that the server should execute. 
The method being invoked is specified 
inside the SOAP-ENV : Body XMLtag. 

Although SOAP can be used with a variety of 
protocols, it's almost always used only with 
HTTP. 

You may be wondering exactly what a SOAP 
request looks like. The following is a simple 
SOAP requestto getthe weather conditions for 
a specific station. In the following example, I 
request the weather for KSTL, or St. Louis, 
Missouri: 

<SOAP-ENV:Envelope 

xmlns:SOAP-ENV="http:// 

sch em as. xm lsoap.org/soap/ 

envel ope/ " 
SOAP-ENV:encodingStyle= 

"http://schemas.xm lsoap.org/ 

soap/encodi ng/"> 

<SOAP-ENV:Body> 

<m: GetCurrentTemperature 

xml ns :m="Some-URI "> 

<symbol>KSTL</symbol> 

</m: 

GetCurrentTemperature > 
</SOAP-ENV:Body> 
</SOAP-ENV:Envelope> 
I called the GetCurrentTemperature 
method, passing it one parameter, which is 
called symbol. This is the weather station I am 
querying. 



Defining a Web Service 

Before you create your web service, you should define what it will do. This 
allows you to properly construct the interface that other applications must 
adhere to if they want to communicate with your web service. 

The most basic design decision is which of the two general types of web ser- 
vices you will create: 
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V Synchronous service 
Asynchronous service 




nous web service, which is the default, begins when the web service 
receives a message. This web service responds immediately. 

Synchronous web services are most useful when the client program requires 
the data returned from the request immediately. An example of this type of 
data is the current stock quote for a particular company. 

An asynchronous web service is asynchronous, so messages can be 
exchanged freely between the client and web service. A message from one 
side does not oblige the other to send a corresponding message. When a 
client sends a message to an asynchronous web service, the client doesn't 
wait for a message back from the web service. The web service may send a 
message back to the client at a later time, but nothing inherently ties this 
message to the original message that the client sent. 

\\V ^ Asynchronous web services are a good choice when you're sending informa- 
tion that doesn't require a response. For example, you may want to a send a 
message to several of your servers, giving them a new greeting message to 
display to users. 



Choosing and Buildinq a 
Backend Component 

The purpose of your web service is to allow remote clients to access services 
that you provide. These services, called the backend component, take the 
form of Java code. You can build your backend component as one of the 
following: 

f A method of a stateless session EJB 
V A method of a Java class 
i>* A JMS method consumer 

WebLogic can make any of these items available as a web service. This 
makes it convenient to package existing Java code as a web service. If you've 
already created stateless session EJBs, you can package them as a web ser- 
vice. Or if your code exists in regular Java classes, you can provide access to 
your class as a web service. You can also use JMS messaging as a backend 
service for your web service. JMS is covered in Chapter 15. 
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tion, you build a synchronous web service. I cover using and a regu- 
lar Java class and then using a stateless session EJB. Later, you find out what 
changes are necessary to make this web service an asynchronous service. 

First you must write the backend component. This will be either a Java class, 
a stateless EJB, or a JMS method consumer. 



Working With a JaVa class 
backend component 

You must follow a few rules when implementing a web service operation 
using a Java class: 

Do not start any threads. This rule applies to all Java code that runs on 
WebLogic Server. 

V Define a default no-argument constructor. 

Define as public the methods of the Java class that will be exposed as 
web service operations. 

You must write thread-safe Java code because WebLogic Server maintains 
only a single instance of a Java class that implements a web service opera- 
tion, and each invocation of the web service uses this same instance. 

For an example of implementing a WebLogic web service operation with a 
Java class, go to the following directory: 

UL_H0ME\ samp 1 es\ server \src\exampl es\webservi ces\basic\javacla 
ss 

where UL_H0ME refers to the main directory of your WebLogic Server installa- 
tion. On a Windows system, this directory is usually C:\bea\weblogic81. 

Listing 9-1 shows a Java class that you could use as a backend component. 
This Java class contains a single method, named sampl eMethod, that accepts 
an i nt and returns a Stri ng. 

Listing 9-1 : Java Class Backend Component 

package com . dummi es . ejb ; 

public class Sampl eBackendComponent 
{ 



Chapter 9: Building and Deploying Web Services 



publ i c 
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ca 



it 



ch ( num) 



se 



1 : return 



One" ; 



case 


2: 


return 


"Two" ; 


case 


3: 


return 


"Three" ; 


case 


4: 


return 


" Four" ; 


case 


5: 


return 


" Five" ; 


case 


6: 


return 


"Six"; 


case 


7 : 


return 


"Seven" ; 


case 


8: 


return 


"Eight" ; 


case 


9: 


return 


"Nine"; 


case 


10 


: return 


"Ten" ; 



Working With a stateless session EJB 
backend component 



You may also choose to build your backend component as a stateless session 
EJB. Writing Java code for a stateless session EJB for a web service is no dif- 
ferent than writing a stand-alone EJB. 

In the web-services.xml deployment descriptor, you can specify that a web 
service operation is one way, which means that the client application that 
invokes the web service doesn't wait for a response. When you write the Java 
code for the EJB method that implements this type of operation, you must 
specify that it returns void. 

When choosing between using an EJB or a Java class backend component, 
consider the other ways in which your backend component will be used. If 
your backend component will be commonly accessed as an EJB, build it as an 
EJB. This allows you to use the same code for both your EJB and web service. 

Considerably more resources are required to call a web service than to call 
an EJB. Because of this, it's common to create all your backend components 
as EJBs and then allow external applications to access your backend compo- 
nents as web services. Your own local applications, which are running on the 
same network as your WebLogic server, can use the faster EJB calling 



de 



f aul t : return 



"Some Number" ; 



method. 



For the EJB in this section, you use the stateless EJB developed in Chapter 6. 
You'll see the highlights of that EJB and how they relate to the web service. 
For complete information on creating an EJB, refer to Chapter 6. 
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Listing 9-2 shows the bean file that implements the EJB backend component. 
The EJB backend component is nearly the same as the Java class backend corn- 
he main difference is the additional code used to support the EJB. 



Listing 9-2: EJB Backend Component 



package com . dummi es . ejb ; 

import javax.ejb.*; 

import Java . rmi .*; 

import j avax . swi ng . * ; 

public class SampleBean implements SessionBean 



private Sessi onContext stx; 

//Required methods, not used by this type of bean 
public void ejbCreate( ) { ) 
public void ejbRemove( ) { ) 
public void ejbActi vate( ) { ) 
public void ejbPassi vate( ) { ) 

// setter for the Sessi onContext 

public void setSessi onContext ( Sessi onContext ctx) 

{ 

ctx = this. stx; 



// the sample method 

public String sampl eMethod( i nt num) 
throws RemoteExcepti on 

{ 

switch(num) 

{ 

case l:return "One"; 

case 2 : return "Two" ; 

case 3:return "Three"; 

case 4 : return " Four" ; 

case 5 : return " Five" ; 

case 6 : return "Six" ; 

case 7:return "Seven"; 

case 8 : return "Eight" ; 

case 9 : return "Nine" ; 

case 10:return "Ten"; 

defaul t : return "Some Number"; 
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You must specify that the bean is a stateless EJB in the ejb-jar.xml file, 
which is shown in Listing 9-3. You can use many nodes and attributes, 
information on the structure of an ejb-jar.xml file, refer to 



Listing 9-3: ejb-jar.xml File for a Backend Component 



<!D0CTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc. //DTD 


Enterprise JavaBeans 2.0//EN' 


'http://java.sun. com/dtd/ejb- jar_2_0 . dtd ' > 


<ejb-jar> 




<enterprise-beans> 




<sessi on> 




<ejb-name>SampleObject</ejb-name> 


<home>com.dummies.ejb.Sampl eHome</home> 




<remote>com. dummi es.ejb.Sample</remote> 




<ejb-class>com . dummi es .ejb.SampleBean</ejb-c 


1 ass> 


<session-type>Stateless</session-type> 




<transaction-type>Container< 


/transact!' on-typ 


e> 


</sessi on> 






</enterprise-beans> 






</ejb-jar> 







Building an Asynchronous Web Service 

In general, you build the backend component for an asynchronous service 
just as you would a synchronous service. When creating a backend compo- 
nent for an asynchronous service, keep the following in mind: 

The backend component that implements the operation must explicitly 
return void. 

You can't specify out or i n-out parameters to the operation; you can 
specify only i n parameters. 

Asynchronous web services do not return a result when sent a request. Your 
client will not even know whether the web service received the request. 

Nearly all web services are synchronous style rather than asynchronous 
style. Before you choose to create an asynchronous service, make sure 
that it will truly fit your needs. Pure broadcast communication, in which 
you expect no result and don't care whether your message was received, 
is the only appropriate time to choose an asynchronous service. 
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tion, you find out how to package your web service. Packaging is the 
process that connects your backend component with WebLogic in such a way 
that WebLogic makes the backend component available as a web service. 

The packaging process that WebLogic uses for web services relies heavily on 
Ant (developed by the Apache Software Foundation). Ant is a tool that exe- 
cutes scripts designed to carry out tasks for Java programs. The most 
common use for Ant is to create build scripts for Java programs. 

The following steps assume that Ant is part of your system path. WebLogic 
uses a customized version of Ant, and you must use their version. 



Packaging a synchronous service 

You must create a custom build.xml file to show Ant how to build your web 
service. Such a build.xml file is shown in Listing 9-4. 



Listing 9-4: build.xml File for a Synchronous Web Service 



<project name="bui 1 dWebse 


rvice" default="ear"> 


<target name="ear"> 




<servi cegen 




destEar="TestWebSer 


\/i ce .ear" 


contextURI="testWebServi ce" > 


<servi ce 




ejbJar="EJBSample.jar" 


targetNamespace= 




"http : //l ocal host/webservi ces/TestWebServi ce" 


servi ceName="TestWebServi ce" 


servi ceURI = "/TestWebServi ce" 


gene rateTypes=" True 




expand Me thods= "True 




style="rpc" > 




<cl i ent 




packageName= 




" com . dummi es.webservices.TestWebService" 


/> 




</servi ce> 




</servi cegen> 




</target> 




</project> 
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A number of attributes are shown in the build.xml file. Attributes for the 
servicegen node are listed in Table 9-1. Attributes for the servi ce node are 
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Table 9-1 




servi cegen Node Attributes 




Attribute 


Required? 


Default 


What It Is 




contextURI 


No 




value of 


Defines the URI used to access 








war in a we 


the web service. 




U C o L l_ □ I 


Yes 






Contains the name of the EAR 
file that will contain the final 
web service. This file is 
deployed to WebLogic when 
you deploy your web service. 


overwri te 


No 




true 


Specifies whether you want to 
overwrite any previous 
versions of your web service. 


warName 


No 




web- 

servi ces . 
war 


Specifies the name of the web 
application. You should 
generally stick with the default 










value for this attribute. 






Table 9-2 




serv 


ice Node Attributes 




Attribute 




Required? Default 


What It Is 




ejbJar 




No 




Specifies the name of the 
JAR file that contains the 
EJB — if the backend com- 
ponent forthis web service 


is an tjB. it you aonispec- 
ify this attribute, you must 
include the javaCl ass- 
Components attribute. 


excl udeEJBs 




No 




Contains a comma- 
separated list of EJB 
names for which non- 
built-in data type compo- 
nents should not be 
generated. 


(continued) 
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Table 9-2 (continued) 



dBoo^ 

expandM 



Required? Default What It Is 



pandMethods No 



f al se 



Specifies whether a sepa- 
rate <operati on> 
element for each method of 
the EJB or Java class is 
used, or whether the task 
should implicitly refer to all 
methods. This attribute 
should be true or f al se. 



generateTypes No 



true Specifies whether the 

serialization class and Java 
representations for non- 
built-in data types should 
be generated. This attribute 
should be true or f al se. 



i ncl udeEJBs 


No 




Contains a list of the EJB 
names that use non-built-in 
data types. 


javaClass- 
Components 


No 




Contains a comma- 
separated list of classes — 
if the backend component 
is one or more Java 



JMSActi on 



Yes, if 
using JMS 



JMSConnecti on - Yes, if 
Factory using JMS 



classes. These classes 
must be compiled and be 
part of CLASSPATH. If you 
don't specify this attribute, 
you must include the 
ejbJar attribute. 



Specifies whether the 
client application that 
invokes this JMS- 
implemented web service 
sends messages to or 
receives messages from 
the JMS destination. This 
attribute should contain the 
value Send or Recei ve. 



Specifies the JNDI name of 

Connecti onFactory 
used to create a connec- 
tion to the JMS destination. 
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Attribute 


Required? 


Default 


What It Is 






Yes, if 
using JMS 




Specifies the JNDI. This 
attribute should contain the 
name of a JMS topic or 
queue. 


JMSDesti nati on- 
Type 


Yes, if 
using JMS 




Specifies the type of JMS 
destination. This attribute 

chnnlH nnntain tho waliro 


Queue or Topi c. 


JMSMessageType 


No 


Java . 
lang. 

Stri ng 


Specifies the data type of 
the single parameter to the 
send or receive operation. 


JMSOperat ion- 
Name 


No 


send or Specifies the name of the 
recei ve, operation in the generated 
depending Web Service Definition 
on the value Language (WSDL) file, 
of the which is the file that 
JMSActi on defines the methods of your 
attribute web service. 


protocol 


No 


http 


Contains the protocol over 
which this web service is 
deployed. This attribute 
should be http or https. 




servi ceName 


Yes 




Contains the name of the 
web service that will be 
published in the WSDLfile. 


servi ceURI 


Yes 




Contains the web service 
URI portion of the URL used 
by client applications to 
access your web service. 


Always include the leading 
slash (/), for example 

/TestWebServi ce. 


styl e 


No 


rpc 


Specifies whether RPC- 
or documents-oriented 
operations are used. This 
attribute should be rpc or 

document. 


targetNamespace 


Yes 




Contains the namespace 
URI of the web service. 
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Table 9-2 (continued) 
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typeMaj 



Required? Default What It Is 



ppingFile No — Specifies a file that 

contains additional XML 
data-type mapping infor- 
mation. This data is added 

to web-servi ces . xml . 



You can also define several attributes for the client node, as shown in Table 
9-3. The client node allows you to automatically generate a stub that a 
client would use to access the web service. A stub is a small class used to 
interface to the web service. The client communicates with the stub, which in 
turn communicates with the web service. This process is discussed in 
greater detail in Chapter 10. If you don't want to create an interface for the 
client to use when accessing your web server, you're not required to include 
this client node. If you don't create such an interface, you need to use the 
cl i entgen utility later when you want to access this web service from a 
client. Using web service clients is covered in Chapter 10. 



Table 9-3 


cl i e 


n 


t Node Attributes 




Attribute 


Required? 




Default 


What It Is 




cl i entJa rName 


No 




servi ce 
cl i ent . 


\lame_ Contains the name of the 
j a r generated client JAR file. 


packageName 


Yes 






Contains the package 



name into which the 
generated client inter- 
faces and stub files are 
packaged. 



saveWSDL No true Generates WSDL and 

stores it in the JAR file. 
This prevents clients 
from having to generate 
WSDL each time. 

useServerTypes No false Specifies whether the 

client should use the 
definition for any 
non-built-in types from 
the EAR file. 
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To package your web service, follow these steps: 
our environment. 



If you're using Windows, execute the setEn v . cmd command, 
located inC:\bea\weblogic81\server\bin. 



• If you're using UNIX, execute the setEn v . sh command, located in 

C : \bea \ we blogic81 /server/ bin. 

2. Create a staging directory. 

You need to create a temporary staging directory to hold the compo- 
nents that will make up your web service. For this example, I assume 
you're using c:\staging as your staging directory. 

3. Package the backend component. 

• If the backend component is implemented using an EJB, make sure 
that your EJB is packaged as an EJB JAR file. This is covered in 
Chapter 6. Place the EJB JAR file in the staging directory. 

• If the backend component is implemented using a Java class, com- 
pile it to a Java .class file and place the .class file in the staging 
directory. 

4. Create an Ant build file and place it in the staging directory. 

Create a custom build.xml file, as shown in Listing 9-1. 

5. Execute the Ant build file by typing ant from the staging directory. 

Ant builds your web service as an EAR file, as shown in Figure 9-1. You're 
now ready to deploy your web service. 




After completing these steps, you have an EAR file that contains your web 
application. You're now ready to deploy this EAR file to your WebLogic Server. 
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Packaging an asynchronous service 



an asynchronous web service is nearly the same as building a syn- 
s web service. The main difference is that the styl e attribute in the 
build.xml file specifies message rather than rpc. This designates the web ser- 
vice as an asynchronous web service. 



Listing 9-5: build.xml File for an Asynchronous Service 

<project name="bui 1 dWebservi ce" default="ear"> 
<target name="ear"> 
<servi cegen 

destEar="TestWebService.ear" 
contextURI="testWebServi ce" > 
<servi ce 

ejbJar="EJBSample.jar" 
ta rgetNamespace= 

"http://localhost/webservices/TestWebService" 
servi ceName="TestWebServi ce" 
servi ceURI = "/TestWebServi ce" 
genera teTypes= "True" 
expandMethods="True" 
style="rpc" > 
<cl i ent 

packageName= 
" com . dummi es.webservices.TestWebService" 

/> 

</servi ce> 
</servi cegen> 
</target> 
</project> 



Deploying \lour Web Service 

A web service is packaged to an enterprise archive (EAR) file. Because of 
this, the steps to deploy a web service are nearly the same as deploying an 
enterprise application, as described in Chapter 8. In this section, I cover the 
process from a web service point of view. 

After you've packaged your web service to an EAR file, you can repeat the 
deployment step as many times as needed. This provides a convenient way 
to distribute your web service to any number of servers. 
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Follow these steps to deploy your web service: 
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re that WebLogic Server is running, and log on to Administration 

ole athttp://localhost:7001/console. 

2. In the left pane, click the Deployments folder, and then click the 
Applications folder. 

The screen shown in Figure 9-2 appears. 

3. Click the Deploy a new Application link. 
The screen shown in Figure 9-3 appears. 

4. Upload your file. 

Click the upload your filers') link, type the name of the EAR file that 
you'll be uploading to the server, and then click Upload. 

5. Click the radio button that appears next to your newly uploaded EAR 
file, and then click Continue, as seen in Figure 9-4. 



Figure 9-2: 

Current 
enterprise 
applications. 



e] WelrLorjic Seivei Console - Microsoft Internet Explorer 



File Edit View Favorites Tools Help 



©Back 'Q'[k)10 j ^Search ^Favortes ^Media | ^ H Q> 

bj http : //localhost : 700 1 /console/actions/mbean/MBeanFrameset Action?bodyFrameId=wl_console Jrame_l Q4iM5::i6i:ii:i754&isNe vj Q Go 



• Console 

H 9 mydomain 
0 CJ Setvers 
CJ Clusters 
CJ Machines 
□ 28 Deployments 
CJ Applications 
dJEJB Modules 
CJ Web Application Modules 
CJ Connector Modules 
Cl Startup & Shutdown 
S CJ Services 
S CJ Security 

LJ Domain Log Filters 
CJ Tasks 



1 



mydomain> Application 



Connected to : localhost 7001 | You are I 




i in as : admin | Logout 



An application is a J2EE application or Web Service contained in an Enterprise 
Application Archive (EAR) file or exploded EAR directory. Individual components 
contained in a J2EE application can be deployed to one or more target servers or 
clusters. 

When one or more applications have been configured for deployment in the current 
WebLogic Server domain, this Applications page displays key information about the EAR 
files or exploded EAR directories. To configure an application for deployment, click the 
Deploy a new Application link. 

^ Deploy a new Application 



■g] Applet navapplet started 
^^ym^^" 1 testate Server -"C:\be.. 



3 WebLogic Server Con,., 



*J Local intranet 

7:34 AM 
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«y Wel>Lo(jic Server Console Microsoft Internet Explorer 

File Edit View Favorites Tools Help 

\m] \£\ ^) J2> Search Favorites 



Figure 9-3: 

Configuring 
a new 
application. 



^Media 



i7localho£t:7001/console/actions/mbean/MBeanFramesetAction?bo vj £j Go 



• Console 



Q myclornain 
S CJ Servers 
CJ Clusters 
CJ Machines 
0 Deployments 
CJ Applications 
C_J EJB Modules 
_J Web Application Modules 
LJ Connector Modules 
C2 Startup & Shutdown 
Ltl CJ Services 
13 C2 Security 

CJ Domain Log Filters 
CJ Tasks 



Connected to : localhost 7001 | You are logged in as : admin | Logout 



licatio 



Select the archive for this application 

Select the file path that represents your archive or exploded archive directo . 

Note: Only vali d fi le paths are shown below. If you do not fi nd what you are 
you should upload your filets) and/or confirm your application contains valid 
descriptors. 



Location: localhost \ C: \ bea \ user projects \ mvdomain 





□ applications 






□ mvserver 





[<L 



£j Applet navapplet started 
jfcfl^J^^^ ' t^5tart5erver-"C:\be... 



3 WebLogic Server Con... 



*J Local intranet 

I 7:35 AM 



Figure 9-4: 

Selecting 
your 
application. 



iS] WebLogic Server Console - Microsoft Internet Exploier 



File Edit View Favorites Tools Help 

QBack * Q Q g] £j} ^Jsearch "^Favorites ^ Media ^2) 0- ^ [J ^ 



Address httpi/jflrxalrTOhTQjQl/cQnsole/art^^ v \ Go 



• Console 
S 9 mydomain 
Ltl CJ Servers 
CJ Clusters 
CJ Machines 
□ 9 Deployments 
_J Applications 
Ul EJB Modules 
C2 Web Application Modules 
CJ Connector Modules 
LtJJ Startup & Shutdown 
Ltl Cj Services 
Ltl CJ Security 

CJ Domain Log Filters 
CJ Tasks 



y an Application 



t the archive for this application 

tthe file path that represents your archive or exploded archive directory. 

Only validfile paths are shown below. If you do not find what you are looking foi 
lould upload your filets) and/or confirm your application contains valid 
iptors. 

Location: localhost \ C: \ bea \ user projects \ mvdomain \ mvserver \ 
upload 



1* 

] 



iMyApp.ear 



a! 



Applet navapplet started 



r-j r .... L ^ 



'C:\be... 



5 WebLogic Server Con.. 
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6. Type a name for your application, and then click Deploy. 

After a few moments, the deployed status changes to Success, as shown 
gure 9-5. 



Your web service is deployed and ready for use. Chapter 10 describes how to 
use your newly deployed web service. 



Figure 9-5: 

Your appli- 
cation is 
deployed. 



v " WelrLorjic Seivet Console Microsoft Internet Exploier 

File Edit View Favorites Tools Help 



Q 6 ** ' Q [*} [~\ _ | S ) /-^Search ^Favorites Media 5^ ^ ^ 

- . ; http://localhost:7001/console/actiora^^ v lJ Go 



• Console 

Q> mydomain 
B CJ Servers 
□ Clusters 
CJ Machines 
B Deployments 
B Cl Applications 
CJEJB Modules 
CJ Web Application Modules 
CJ Connector Modules 
C2 Startup & Shutdown 
B CJ Services 
B d Security 

CJ Domain Log Filters 
CJ Tasks 



Connected to : 


localhost 7001 [ 


You are logged in as : admin 


| Logout 










Configuration 


Targets 


Motes 





This page allows you to view the deployment status of each module in the 
application, and to stop or redeploy individual modules. You may also choose to 
stop and redeploy all modules within the application using the buttons at the 
bottom of the page. (To configure additional deployment targets for this 
application, click the Targets tab.) 

Deployment status foi EJB Modules 



Module 


Module 
Status 


Target 


Target 
Type 


Status of 
Last Action 


EJBSample iar 


Active 


mvserver 


Server 


Success 



Deployment Status foi Web Application Modules 





Module 


Module 
Status 


Target 


Target 
Type 


Status of 
Last Action 


testWebService 


Active 


mvserver 


server 


Success 



liL 



Stop Application Redeploy Application 



s] Applet navapplet started 



^UMjtej' 1 fj Start Server -v-|be.. 



3 WebLogic Server Con... 
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Chapter 10 

DropBooks . ... , n . 

Accessmq Web Services 



In This Chapter 

Using a static client 
Using a dynamic client 



EM J eb services are an increasingly popular way to access remote applica- 
WW tions. Web services exchange information with their clients using XML 
constructed according to the SOAP protocol. (For more on the SOAP protocol, 
see Chapter 10.) In this chapter, you find out how to access a web service using 
WebLogic. If you're interested in creating web services, refer to Chapter 9. 

You can create two types of web service clients with WebLogic: a static client 
that uses stub client interfaces created by WebLogic and a dynamic client 
that learns about the web service as it runs. Static clients are easy to pro- 
gram and use. Dynamic clients require more source code but add flexibility 
These are shortcuts that WebLogic provides to make it easier for WebLogic 
developers to work with web services. 

When accessing a WebLogic web service, always use a static client. Use a 
dynamic client when you're accessing a non-WebLogic web service or a web 
service whose interface you may want to change as the program runs. In rare 
situations, your program may not know the structure of the web service 
beforehand. A dynamic client can adapt to many types of web services. 



Using a Static Client 

In this section, you find out how to create a static web service client. A static 
client uses the web service EAR file to generate a client stub that you can use 
to call the web service, just as if it were a local class. The main difference 
between a static client and a dynamic client has to do with how you call the 
web service. In a static client, you call a web service just like any other Java 
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method. In the dynamic client, you must call methods to specify the method 
name, parameters, and return type. This allows these values to be different 
.e the client runs. 



p Book's 

Understanding U/SDL 




Web Service Definition Language (WSDL) provides instructions for accessing 
a web service. You use the WSDL of your target web service to create a client 
stub. After you generate this client stub, you can access the web service as 
though it were a regular Java class. 

WSDL is an XML-formatted description of a web service. This code contains 
all the necessary information to access a web service. You can find out more 

at http : / /www .w3 .org/TR/wsdl. 

To access the WSDL file contained in a web service, you first must make 
sure that you have a web service deployed on WebLogic. For this example, 
I assume that you're using the TestWebService web service from Chapter 9. 
You can access this web service with the following URL: 



http : //l ocal host 


:7001/testWebService 


/TestWebServi ce 




You can see the WSDL file for youi 


" web service by accessing the following URL: 


http ://! ocal host 


:7001/test 


.WebService/TestWebService? 


WSDL 



If your web service has been properly configured, the screen displays some- 
thing similar to Figure 10-1. (If you don't see your WSDL file, your web service 
is not up and running. Review Chapter 9 for information on creating and 
deploying your web service.) 

The WSDL file in Figure 10-1 is complex, but you don't need to be able to read 

the file to access a web service. Reading this file is the job of the WebLogic 

cl i entgen application. You find out how to use cl i entgen in the next section. 

Following are the steps you need to take to create a static web service client: 

1. Generate a client stub. 

2. Create a client program that will use the client stub. 

3. Start WebLogic Server. 

4. Run the web service client application. 

In the following sections, I expand upon these steps. 
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i hrt|>: localliost:7001'testWebService/TestWebServke?WSDL - Microsoft Internet Explorer 
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Figure 10-1: 

Looking at a 
WSDLfile. 



File Edit View Favorites Tools Help 

[X 1 Z . s i j ' Search 



l//locdhost7001/test l .Veb5ervi.:e/TestWeb5ervice?WSDL 



IB* 



<?xml version="l,0" encoding="utf-8" ?> 

<definitions ;-:mlns: i-="http ://w wvv.vj3.org/2001/XMLSchema" 
xmlns: http="http://schemas. xmlsoap.org/wsdl/http/" 
xmlns: soap="http://schemas. xmlsoap.org/wsdl/soap/" 
xmlns: soapenc="http://schemas. xmlsoap.org/soap/encoding/" 
xmlns: tns="http://localhost/webservices/TestWebService" 
xmlns: mime="http://schemas. xmlsoap.org/wsdl/mime/" 
targetNamespace='http://localhost/webservices/TestWebService" 
xmlns="http://schemas. xmlsoap.org/wsdl/"> 

- <message name="sampleMethod"> 

<part name="intVal" xmlns: partns="http://www. w3.org/2001/XMLSchema" 
type- 'partns:int" /> 
</message> 

- <message name="sampleMethodResponse"> 

<part name="result" xmlns: partns="http://w ww.w3.org/2001/XMLSchema" 
type="partns:string" /> 
</message> 

- <portType name-"TestWebServicePort"> 
- <operation name="sampleMethod"> 

<input message="tns:sampleMethod" /> 
<output message="tns:sampleMethodResponse" /> 
</operation> 
</portType> 

- <binding name="TestWebServicePortSoapBinding" type-"tns:TestWebServicePort"> 

<soap: binding style="rpc" transport="http://schemas. xmlsoap.org/soap/http" /> 



r_j Done 



* J Local intranet 



Start Server - C:\bea. . 



3 http:|fyiocatiost:7001,., 



Generating the client stub 

To use the web service created in Chapter 9, you must create a client stub for 
that application. This stub allows you to access the web service as though it 
were a regular application. The client stub generation process that WebLogic 
uses for web services relies heavily on Jakarta Ant. Ant is a tool that executes 
scripts that carry out tasks for Java programs. The most common use for Ant 
is to create build scripts for Java programs. 




WebLogic uses a customized version of Ant, so you must use the version of 
Ant provided by WebLogic. Ant is stored in the WebLogic b i n directory. The 
following steps assume that Ant is part of your system path. 



You must create a custom build.xml file to show Ant the URL for which you 
want to build a web service. Such a build.xml file is shown in Listing 10-1. 



Listing 1 0-1 : build.xml File for Client Stub Generation 



<pro ject 

name=" bull dWebservi ce" 
def aul t=" genera te-cl i ent"> 



(continued) 
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Listing 10-1 (continued) 

<target name="generate-client"> 
i entgen 

ar="TestWebService.ear" 
serviceName="TestWebService" 
packageName="com . dummi es .webservices .TestWebServi ce" 
useServerTypes=" Fal se" 
clientJar="TestWebServiceClient.jar" /> 
</target> 
</project> 

cl i entgen automates the creation of the client stub. To use cl i entgen, you 
must create an Ant script. You can define quite a few attributes to control the 
operation of cl i entgen. These attributes are summarized in Table 10-1. 



Table 10-1 cl i entgen Attributes 

Attribute What It Is 



ear The enterprise application that contains the web 

service. For more information on how to generate this 
file, see Chapter 9. 



servi ceName 


The name of your web service. 




packageName 


The pack 
stub into. 


age name that you want to place yoi 


ir client 


useServerTypes 


Determ 
This atti 


n 

-il 


es whether custom data types should be used. 
:ute should contain true if you're using the 



data types of the server or fal se for customized data 
types. 

cl i entJa r The name of the JAR file that you want the client stub 

generated to. 



After you create the build.xml file, you can execute it by typing the Ant com- 
mand from the same directory as the build.xml file. When you do so, the 
screen shown in Figure 10-2 appears. 



Building the client application 

Now that you've created the client stub file, you must create an application 
that makes use of the web service. Listing 10-2 shows such an application. 
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Figure 10-2: 

Building the 
client file. 



:\UebLogicExamples\cM0>ant 
u: ldf ile: build. xnl 

I 3i ' *att -*-lient: 

' c ie 't^en Generating client jar for TestUebSeruice .earCTestllebSeruice) ... 

ic j.ieri±g<..i J Generating Java classes and serializers fron USDL <f ile i/Ci/DOCUME""! 

jheaton/'LOCALS^l/Temp/TestUebSerw iceClient . jar5 19 1578 37/con/dunnies/webserv ices 

TestWebSerMice/TestWebSeruice .wsdl> . . . 

[clientgen ] Compiling 4 source f iles to C:\DOCUME~l\jheaton\LOCflLS~l\Tenp\TestWe 
bSerMiceClient . jar519157837 

[clientgen ] Building jar: C:\WebLogicExanples\chl0VTestWebS 
UILD SUCCESSFUL 




Listing 10-2: Web Service Client 

import com . dummi es.webservices.TestWebService.*; 

public class StaticClient { 

public static void mai n ( Stri ng[ ] args) throws Exception I 
// Set up the global JAXM message factory 
System.setPropertyC'javax.xml.soap.MessageFactory", 

"weblogic.webservice.core.soap.MessageFactorylmpl" 
); 

// Set up the global JAX-RPC service factory 
System. setProperty( "javax.xml .rpc.ServiceFactory", 

"weblogic.webservice.core.rpc.ServiceFactorylmpl") 

// Parse the argument list 
StaticClient client = new StaticCl ient( ) ; 
String wsdl = (args. length > 0? args[0] : null); 
cl ient.example(wsdl ) ; 

) 

public void exampl e(String wsdlURI) throws Exception { 
TestWebServi cePort client = null; 
if ( wsdlURI == null ) { 
cl i ent = new 

TestWebServi ce_Impl ( ) . getTestWebServi cePort( ) ; 
} else { 
cl i ent = new 

TestWebServi ce_Impl (wsdl URI ) . getTestWebServi cePort 
(); 

) 

// call the method 

System . out . pri ntl n ( trader . sampl eMethodO ) ); 

) 

) 
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mi 



The program works as follows. First, you set up the JAXM factory and the 
RPC factory. A factory is a class designed to create other objects. For exam- 
uses the ja vax . xml .soap. Message Factory class as a factory to 



essages. You should not change anything in these lines, and they 
must be included with a client application: 

// Set up the global JAXM message factory 
System.setPropertyC'javax.xml.soap.MessageFactory", 

"weblogic.webservice.core.soap.MessageFactorylmpl" 
); 

// Set up the global JAX-RPC service factory 
System. setProperty( "javax.xml .rpc.ServiceFactory", 

"weblogic.webservice.core.rpc.ServiceFactorylmpl") 



Next, you create an instance of the port class. This object is used to connect 
to the web service, as seen here: 

TestWebServi cePort client = null; 
if ( wsdlURI == null ) { 

client = new TestWebServi ce_Impl (). getTestWebServi cePort () ; 
) else { 

cl i ent = new 

TestWebServi ce_Impl (wsdlURI). getTestWebServi cePort 
(); 

) 

In the preceding code, you check to see whether the user has passed in an 
alternate URL to use with the service. If no alternate URL was passed in, you 
use the URL built into the web service WSDL: 

// call the method 

System . out . pri ntl n ( trader . sampl eMethodO ) ); 

When you compile the program, make sure that both the J2EE and client stub 
JAR files are in cl ass path. To do so, compile Listing 10-2 with the following 
command: 

javac -classpath TestWebServi ceCl ient .jar ; 
C:\bea\weblogic81\server\lib\webserviceclient.jar 
Stati cCl i ent . java 



I included the webserviceclient.jar file in the command. You may need to 
include a different version of this JAR file; refer to Table 10-2. 
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Table 10-2 


Web Service Client JAR Files 


-\[&ltfile When to Use It 


webserviceclient.jar 


When you don't need SSL to access your web 




service 


webserviceclient+ssl.jar 


When you need SSL to access your web service 


webserviceclient+ssl_pj.jar 


With the CDC profile of J2ME 



Running the client application 

To run your client application, you must execute it with the WebLogic web 
services client and the client stub JAR files present. To do so, use the follow- 
ing command: 



Java -classpath TestWebServi ceCl i ent . jar ; 
C:\bea\weblogic81\server\lib\webserviceclient.jar;. 
Stati cCl i ent 



After you execute your application, you'll see the result of calling the web 
service. Figure 10-3 shows the client program being executed. 



Figure 10-3: 

Running 
the client 
application. 



i:\UebLogicExanples\c hi 0>jaua -classpath TestWebSeruiceClient . jai* ;C:\bea\weblogi| 
:700Sseruei*\lib\websei*uiceclient .Jar; . StaticClient 
"hree 

) :\UebLogicExanples\chl0> 



You probably noticed a delay of a few seconds before the output was dis- 
played. This is a result of the overhead that the web service incurs as the 
JVM starts up and data is posted between the web server and web client. The 
overhead for a web service is considerably more than that for an EJB. As a 
result, you should use EJBs for your program's internal use. Use web services 
to allow external applications to access your EJBs through the Internet. 
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In this section, you found out how to call a client using a static connection to 
the web service. You can also choose to call your web service dynamically, a 
cribed in the next section. 



Using a Dynamic Client 



A dynamic client can change virtually anything about the way in which the 
web service is accessed at run time. All information about which web service 
to access is given dynamically to Java. I will begin by showing you how to 
construct the dynamic client. 



Constructing the dynamic client 

Producing a dynamic client involves fewer steps than producing a static 
client because a dynamic client doesn't require a client stub file. However, 
calling methods through the dynamic interface is not as natural for a Java 
programmer. 

In addition, method names and parameters are specified as strings, so you 
won't catch errors when compiling. If you specify the wrong method name for 
the dynamic client, you won't know until your program runs. Specifying an 
invalid method name with a static client would cause a compile error. The 
complete dynamic client source code is shown in Listing 10-3. 



Listing 10-3: Dynamic Client 

import j ava . uti 1 . Properti es ; 
import j ava . net . URL ; 
import j avax . nami ng . Context ; 
import j avax. nam ing.InitialContext; 

import weblogic.soap.WebServiceProxy; 

import weblogic.soap.SoapMethod; 

import webl ogi c . soap . SoapType ; 

import weblogic. soap. codec. CodecFactory; 

import weblogic. soap. codec. SoapEncodingCodec; 

import weblogic. soap. codec. LiteralCodec; 

public class Dynami cCl i ent I 

public static void main( String[] arg ) throws Exception! 



CodecFactory factory 



= CodecFactory . newlnstance( ) 
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factory . regi ster ( new SoapEncodi ngCodec( ) 
factory . regi ster ( new Literal Codec( ) ); 

( If pj |j (J |\ li^bServi ce Proxy proxy = WebServi ceProxy . createServi 

f * w w i xw new URL( 

" h + + n • / /lncalhnct.7nm /toctUohCorui ro /ToctlJi 



); 

ce( 



URL( 

"http://local host : 7001 /testWebServi ce/TestWebServi 
ce" ) ); 

proxy . setCodecFactory ( factory ); 
proxy . setVerbose ( true ); 

SoapType param = new SoapType( "intVal", Integer . cl ass ); 
proxy . addMethod( "sampl eMethod" , null, new SoapType[]{ 
param ) ); 

SoapMethod method = proxy . getMethod( "sampl eMethod" ); 

Object result = method . i nvoke ( new 0bject[]{ new 
IntegerO)} ); 



First, you must register the correct codecs. A WebLogic codec, which stands 
for code/decode, translates Java objects to and from SOAP XML. (When the 
term codec is used with multimedia files such as MPEG and Quicktime, it 
means compressor/decompressor.) If you're missing a codec, you get an 
error when you transmit your request: 

CodecFactory factory = CodecFactory .newlnstance( ) ; 
factory . regi ster ( new SoapEncodi ngCodec( ) ); 
factory . regi ster ( new Li teral Codec( ) ); 

A proxy must be set up that will get your method context. The proxy is used 
as an intermediary to connect to the web service and ultimately to allow you 
to communicate with the web service. You use the method context to send 
your method call: 

WebServi ceProxy proxy = WebServi ceProxy . createServi ce ( 
new URL( 

"http://local host : 7001 /testWebServi ce /TestWebServi 
ce" ) ); 

proxy . setCodecFactory ( factory ); 

The method context is very important. The method context is the object that 
you use to invoke methods on the web service. If any errors are reported, 
they should be reported verbosely, which means with as much detail as possi- 
ble. The following command sees to this: 

proxy . setVerbose ( true ); 
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Next, parameters must be constructed, sampl eMethod takes one parameter, 
an i nt, and returns a string: 



e param = new SoapType( "intVal", Integer . cl ass ); 



Next, sampl eMethod is obtained using the method name and parameter 
array: 

proxy . addMethod( "sampl eMethod" , null, new SoapType[]{ param 
) ); 

SoapMethod method = proxy . getMethod( "sampl eMethod" ); 

Finally the method is invoked, passing 3 as the parameter. The result is then 
displayed: 

Object result = method . i nvoke ( new Object[]{ new IntegerO)) 
); 

System . out . pri ntl n ( result ); 

To compile this application, you must make sure that the WebLogic JAR file is 
inclasspath. The following command compiles the client: 

javac -classpath 

TestWebServiceClient.jar;C:\bea\weblogic81\server\ 
1 i b\webl ogi c . jar Dynami cCl i ent . java 

Now that you've compiled the client, you're ready to run it. 



Running the dynamic client 

To run the client application, the WebLogic JAR file must be in classpath. 
The following command runs the client application: 

java -classpath 

TestWebServiceClient.jar;C:\bea\weblogic81\server\ 
1 i b\webl ogi c . jar ;. Dynami cCl i ent 

This program, like the static client example, outputs the word three to the 
console. 

In this chapter and in Chapter 9, you create and use web services. In Chap- 
ter 11, you use WebLogic Workshop, which is a GUI tool provided by 
WebLogic to assist in the creation of web services. 




Chapter 11 



sing WebLogic Workshop 



In This Chapter 

Creating a web service with Workshop 

Debugging your web service 

Packaging and deploying your web service 




treating a web service can be difficult, especially for those unfamiliar with 
J2EE. That's why BEA introduced WebLogic Workshop, a full-featured IDE 
for creating and debugging web services. WebLogic Workshop was designed 
to help several groups of people: 

V Non-J2EE programmers who want to create web services 

Non-technical designers who want to create web services 

Advanced J2EE developers who want to become more productive by 
allowing debugging 

Many non-Java languages that use web services include similar IDEs. 
Resource Workshop simplifies Java web service programming. Regardless of 
which group you're in, read on to find out how to create your own web ser- 
vice using WebLogic Workshop. 



The web service you create will be similar to the one in Chapter 9. But in 
Chapter 9, you create the web service manually. In this chapter, you use 
Workshop to perform many of the mundane tasks of setting up the web ser- 
vice and the configuration files. 

The following general steps are required when creating a web service: 
1. Create a Workshop application. 



Creating a Web Service 



2. Create your web service. 
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3. Add methods to your web service, 
your web service. 




Creating a Workshop application 
and a Web service 

The first step in creating a web service with Workshop is to create an applica- 
tion file. This file will hold not only web services, but also EJB and database 
connections. 

It's not necessary to have WebLogic Server running to start WebLogic 
Workshop. Instead, you can start WebLogic Server from WebLogic Workshop. 

To create an application file and a web service, follow these steps: 

1. Start BEA WebLogic Workshop. 

Choose StartCBEA WebLogic Platform 8.10WebLogic Workshop. The 
screen shown in Figure 1 1-1 appears. 
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2. Create an application by choosing FileONewO Application, 
a name for your application, and then click Create. 



How along with the example, type WorkshopWebService for the 

name, as shown in Figure 1 1-2. 



/ Application 



Figure 11-2: 

Creating an 
application. 
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Creates a new Workshop application with a web project and schema project, 
Additional projects may be added later. 



4. Right-click WorkshopWebService (from the tree at the left under the 
Application tab) and choose NewOWeb Service. 

The Create New File dialog box appears. 

5. Type a name for the web service. 

To follow along with the example, type MyService, as shown in 
Figure 1 1-3. 

6. Click OK. 

The screen shown in Figure 1 1-4 appears. Your web service is set up. 

At this point, you've created your application (WorkshopWebService) and 
web service (MyService). In the next section, you add some methods. 



Adding methods to your u)eb service 

For the web service to be of any use, you must add methods to it. Inside the 
methods, you can place Java code that carries out the tasks needed by your 
web service. The methods are called by the client programs that access your 
web service. (For more information on web service clients, see Chapter 10.) 
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Your 
new web 
service. 
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To add a method to the web service, follow these steps: 
the method. 



he Design View tab in the center of the screen (see Figure 11-4), click 
Add Operation and choose Add Method. A method name appears inside 
the web service. 

2. Type a new name for your method. 

To follow along with the example, type myMethod. The screen shown in 
Figure 1 1-5 appears. Now that you've created your method, you need to 
give it some parameters and define its body. 

3. Open the code editor. 

Click the method name to display the code editor. 

4. Program the method. 

Move the cursor into the body of your method and specify a return type 
of St r i ng and a single integer parameter, as shown in Figure 11-6. All 
operations performed by the web service are specified using Java code. 



Figure 11-5: 

Creating the 
method. 
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/** Ocommon: context */ 
JwsContext context; 



* Scommon: operation 

public String myHethod(int i) 

{ 

switch ( i ) 

t 

case 1: return " one" ; 
case 2: return "two"; 
case 3:return "three"; 
case 4: return "four"; 
case 5:return "five"; 
case 6: return "six"; 
case 1: return "seven"; 



default: return "Other Number" 



> 



Content Preview 
User Name: 



> Server Stopped 
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Property Editor ic. 



Your method should match Listing 11-1. 



Listing 11-1: The myMethod Method 



{ 



/** ©common : context */ 
JwsContext context; 



* ©common : operati on 
*/ 

public String myMethoddnt i) 
{ 

swi tch ( i ) 
{ 



case 


1 


return 


"one" ; 


case 


2 


return 


"two" ; 


case 


3 


return 


"three" 


case 


4 


return 


"f our" ; 


case 


5 


return 


"f i ve" ; 


case 


6 


return 


"six"; 


case 


7 


return 


"seven" 



} 

) 

} 
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Now that you've created a method, you're ready to test your web service by 
accessing it using a browser. 



pBooks 

Testing yow? vOeb service 




To test your web service, you must first start the web server. Simply choose 
ToolsOStart WebLogic Server. The server starts and you remain in Workshop, 
as shown in Figure 1 1-7. 

You could test the web service by using a client program, such as the one in 
Chapter 10, but a faster way is to use a browser. 

The browser interface can be used for any WebLogic web service, not just 
web services created with Workshop. 

When you create a web service, it's often for the benefit of some external 
entity, such as a client or a vendor. Because of this, you will rarely develop 
the client applications of a web server. However, you still need a client to test 
your application. 
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If you access the URL of the web service from a browser, you enter a web 
application that WebLogic provides for testing your web service. Using this 
, you can quickly test your web application without the need to 
lient program. 



By default, Workshop uses a web server running on the current machine, 
using port 7001. If you already have WebLogic Server running on that 
machine and port, Workshop fails to start the server. 

Follow these steps to access your web service using its URL and a browser: 

1. Make sure that your web service is running. 

On the Workshop toolbar, click the light blue arrowhead, which is 
labeled in Figure 1 1-8. Workshop automatically opens a browser window 
to your web service, as shown in Figure 1 1-9. 



Start web service 
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Starting 
your web 
service. 
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Qcommon: context: 
JwsContext context; 



Scommon: operation 

public String myHethodfint i) 

< 

switch(i) 

{ 

case 1: return "one"; 
case 2: return "two"; 
case 3: return "three"; 
case 4: return "four"; 
case 5: return "five"; 
case 6: return "six"; 
case 7: return "seven"; 



default: return "Other Hvjifcer" 
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Figure 11-9: 

Accessing 
your web 
service. 



Uprkshoj) Test Browser 



□ ■Oil http!//localho!t:7001/WorkshopWeb5ervke/MyService.lws?.EXPLORE=.TEST 



'Editor Nt,.,\ X 



MvService.jws Web Service 



^ | Overview j ] Console"] | Test Form | | Test XML | ht^://localhost:7Q01/WorkshQpWebService^v1y5ervice,jws 



Test operations 

I M.imi.!ji.i.^aag 



r 



| myMelhorJ | 



Locals 



Name 



3 Server Running Debugging Ln 21 



MyService.jws -BE... I Q Workshop Test Bro... 



| C:\WINDOWS\syst... 



jWebLogic Worksho,., 



_ 



2. Type the parameters for your web service. 

Click the Test Form tab. If you're using the example web service devel- 
oped so far in this chapter, type 1. 

3. Call your method and observe the results. 

Click the button that has the same name as your method (myMethod). 
The results page is shown in Figure 11-10. 

4. End the service. 

To do so, click the red x icon on the toolbar, which is labeled in 
Figure 11-11. 



These steps show you how to test the output that a web service returns for 
the specified input. Although this can be a great aid in debugging, you often 
need more information to debug a program. In the next section, you find out 
how to use the WebLogic debugger. 
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Figure 11-10: 
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the results. 
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Figure 11-11: 

Stopping 
your web 
service. 
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IP includes features that allow you to perform any of the following 
debugging tasks: 

Set breakpoints to pause the web service on particular lines of code 
Inspect the values of variables used by your web service 
Evaluate exceptions thrown as your web service runs 

In this section, you go through a typical debugging session. During this ses- 
sion, you set a breakpoint in your web service. A breakpoint is placed on a 
single line of code to pause program execution when the breakpoint line is 
reached during execution. When the program is paused, you will be able to 
inspect the values of variables and ultimately continue or end execution of 
the web service. 

1. Start your web service. 

Click the Start web service icon, which is labeled in Figure 11-8. 

2. Set a breakpoint. 

Right-click to the left of the switch statement and choose Toggle 
Breakpoint. The screen shown in Figure 11-12 appears. 
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Figure 11-12: 

Setting a 
breakpoint. 
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MyService.jws - [{WorkshopWebService}\] 



{ 



** Gcomman: context */ 
JwsContext context; 



- gcomiiion: operation 
public String myHethod(int i) 



Design View Source View 



Build ! Output Content Preview 



| Property Editor ic... , X 



switch (i) 


{ 

case 1 


return 


'one" ; 


case Z 


return 


' two" ; 


case 3 


return 


1 three " ; 


case 4 


return 


1 four" ; 


case 5 


return 


' five" ; 



Building MyService. jws started. 
(0:0) Build complete - 0 error (s), 0 uarning(s) 
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3. Use a web browser to execute your web service. 



■— ^ | For more 

dBooks^ 



For more information, see the "Testing your web service" section, 
the web service reaches the breakpoint, the screen shown in 
13 appears. 



4. Check the values of your variables after the breakpoint. 

5. To continue execution, click the green arrow. To stop execution, click 
the red dot. 



Figure 11-13: 

The 
breakpoint 
is reached. 
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/** Bcomnon: context 
JusContext context; 



^common: operation 



public String myMethod(int i) 



case 1: return 
case 2 : return 
case 3 : return 
case 4: return 
case 5 : return 



three" ; 
five" ; 
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Building HyService. jws started. 

(0:0) Build complete - 0 error(s), 0 warning(s) 
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After you encounter a breakpoint, a number of actions are available by click- 
ing tools on the toolbar: 

f" Stop. Stops debugging the web service. After you click Stop, you must 
restart the web service to continue debugging. 
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f" Step Into. If you're positioned on a method call, clicking Step Into causes 
the debugger to enter the method rather than pass over it. 

Over. If you're positioned on a method call, clicking Step Over 
es the debugger to skip this method. 

v* Step Out. If you're positioned inside a method call, clicking Step Out 
causes you to leave that method. 

V Continue. Allows the web service to run freely after being stopped. The 
program continues until it reaches the next breakpoint. 



Now that you've used Workshop to create, test, and debug your web service, 
it's time to see how to package and deploy it. 



Packaging and Deploying Web Services 

In the previous sections, you found out how to create and make use of web 
services using only Workshop. Sometimes, however, you'll want to package 
your files for use elsewhere. For example, you might want to 

IV Archive your newly created web service 
Copy your web service to a different development server 
Copy your web service to a production server 

In this section, you find out how to package and deploy your web service. 
You begin by examining the directory structure Workshop creates when you 
create a web service. 



Directory locations 

When you create a web service using Workshop, it creates a web application 
to contain your web service. This web application is stored in the samples 
directory of WebLogic. For example, if you created the WorkshopWebService 
example in this chapter, this web service is stored in the following location: 

C:\bea\weblogic81\samples\workshop\WorkshopWebService 



If you examine this directory, you'll see the same folder structure as was used 
for a web application, as discussed in Chapter 5. The complete directory tree 
used by a web service is shown in Figure 11-14. 
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Figure 11-14: 

The 
directory 
structure 
of a web 
service. 
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Workshop stores your files in a subdirectory of the sampl es directory. This 
might be confusing, in that you may assume that the sampl es directory con- 
tains only WebLogic examples. 



Packaqinq a Web sen/ice 



In this section, you package a web service created with Workshop. The final 
product will be an EAR file. This EAR file contains the enterprise application 
that contains the web service. 

To create the EAR file, you use JwsCompi 1 e. This program, which is invoked 
from a command prompt, has eighteen command-line options but you need 
to concern yourself with only a few of them. 

If you want to see what command-line options are available for JwsCompi 1 e, 
issue the following command: 



jwscompile -help 
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JwsCompi 1 e is in the bi n directory of WebLogic Server. This directory must 
be in your path if you want to execute JwsCompi 1 e from the command line. 



chapter: 



ing command line compiles the sample web service created in this 



JwsCompile -p C:\bea\weblogic81\samples\workshop\ 
WebLogi cWebServi ce -a -ear 
C : \Webl_ogi cWebServi ce . ea r 

The three options in this command follow: 



The - p option specifies the directory that contains the application 
source. WebLogic Workshop placed the example application in the fol- 
lowing directory: 

C:\bea\weblogic81\samples\workshop\WebLogicWebService 

f The - a option specifies that all the files that make up the application 
should be compiled by JwsCompi 1 e. 

V The ear option instructs JwsCompi 1 e to create an EAR file as its output 
and tells JwsCompi 1 e where to place that file. In this instance, the file is 
called WebLogicWebService.ear, and it's placed in the root directory of 
the C: drive. This file contains your web service, packaged and ready to 
deploy. 



Packaging for a different host 

When you execute JwsCompi 1 e, an EAR file is produced that will work for a 
server running on a particular host name and port. The host name used is 
whatever machine JwsCompi 1 e runs on. The default port is 7001, which is 
standard for WebLogic Server. If you want your EAR to run on a different 
machine, you must place the named weblogic-jws-config.xml configuration 
file in the application's WEB - 1 N F directory. 

In a multi-web service application, you might have more than one weblogic- 
jws-config.xml file. You can easily allow more than one web service by speci- 
fying appropriate parameters on the command line when running 
JwsCompi 1 e. By doing this, you can specify an alternate name for the 
weblogic-jws-config.xml file. 



Listing 1 1-2 shows sample a weblogic-jws-config.xml file for deploying the 
WorkshopWebService web service to a machine named MyServer. 
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Listing 1 1 -2: Sample weblogic-jws-config.xml File 



<fconfig> 

dBooISoc, 



be ol >http< /protocol > 
<hostname>MyServer</hostname> 
<http-port>700K/http-port> 
<https- port >7002</https- port > 

<jws> 

<cl ass-name>WorkshopWebServi ce</cl ass-name> 
<protocol>http</protocol> 

</jws> 

</conf i g> 

Table 11-1 describes the purpose of each of the tags in Listing 11-2. 



Table 11-1 


weblogic-jws-config.xml Attributes 




Tag 


What It Is 




protocol 


The protocol to use with this web service. This 
usually contains the string http. 


tag 


hostname 


The host 


name for the computer. 




http-port 


The port 


used with the HTTP protocol. 




https-port 


The port 


used with the HTTPS protocol. 




el ass-name 


The name of the web service. 




protocol 


The default protocol. 





Now that you've seen how to package your web service, it's time to find out 
how to deploy it. 



Deploying uteb services 

Deploying a web service is the same process as deploying an enterprise 
application. The web service is contained in an EAR file. When the EAR file is 
deployed, it implements the web service. 
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The steps to deploy a web service follow: 
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e sure that WebLogic Server is running, and log on to 
inistration Console athttp://localhost:7001/console. 



2. Click the Deployments folder and then the Application folder. 

3. Click the Configure a new Application link. 

4. Type the name of the EAR file that you'll be uploading to the server. 

5. Upload your file, and then click the [select] link that appears next to 
your newly uploaded file. 

6. Target one or more servers by selecting the server on the left and 
clicking the arrow to move it to the list on the right. Type a name for 
your application. Then click Configure and Deploy. 

After a few moments, the deployed status goes to the value of true. 
Your application is now deployed. 

For more information on how to deploy web services, refer to Chapter 8. 
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In this part . . . 

any message services are available with WebLogic. 
In this part you find out how to use four of them: 
JMS, JBDC, JTA, and JNDI. 

JMS (Java Message Service) allows client programs to 
send and receive messages. Messages can be sent from 
one program to one or more programs. JDBC (Java 
Database Connectivity) allows Java programs to access 
database services. You set up JDBC for use with WebLogic 
and use connection pools to more efficiently handle data- 
base access. 

JTA (Java Transactions) allows database requests to be 
grouped into transactions, which will succeed or fail as a 
whole. This allows you to prevent partial transactions 
from occurring due to an error. JNDI (Java Naming and 
Directory Interface) allows Java programs to locate 
named resources on a network. WebLogic uses JNDI to 
access EJBs, connection pools, and other services. 
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In This Chapter 

Configuring a connection pool for your database 
Creating a data source for your connection pool 
Using your data source and connection pool 
Monitoring your connection pool 



A, ta a re a c r „c,a, c„ mp „„e„, o, n e,H y a ny s »cce ss(ul „ eb s „e 
w^or business application. In a distributed application server such as 
WebLogic, managing the connection between many concurrently executing 
instances of an EJB and the database can be difficult. WebLogic acts as an 
intermediary, allowing your EJBs to make the most efficient use of connec- 
tions to the database. 

To use a database from an EJB, you have two options. You can use JDBC to 
directly connect to the database (also known as bean-managed persistence, 
or BMP), just like you would in any other Java program, or you can use 
WebLogic's built-in connection pools to manage your database connections 
(also known as container-managed persistence, or CMP). Regardless of the 
strategy you choose, using WebLogic connection pools can enhance the per- 
formance of your application considerably. In this chapter, you find out about 
both approaches. 
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Creating a Connection Foot 

To use a database in Java, you must first open a connection to that database. 
A database connection is a resource in Java that adds processing overhead, 
so you want to minimize the number of open connections to the database. 
You might think that it would be best to open a database connection, perform 
the operation, and then immediately close the connection. But this approach 
introduces the overhead of opening and closing database connections. The 
overhead of opening a connection can be ten to a hundred times as expen- 
sive as the requested data transfer. The answer to the problem of opening 
and closing connections is to use a connection pool. 
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A connection pool is a group of database connections that remains open to 
the database. When your program needs to access the database, it requests 
tion from the connection pool. The program is then given a connec- 
e for its database operations. To your program, the connection 
seems like a regular database connection. However, you don't close the data- 
base connection when you're finished using it. Instead, you release the data- 
base connection back to the connection pool, so it can be used later. 



The connection pool prevents Java from having to deal with the overhead of 
opening and closing connections. Further, the system is kept from creating 
too many connections and degrading performance. The task of obtaining a 
proper performance balance with the maximum allowable number of open 
connections is left to the system administrator, not the web application logic. 



To create a connection pool, follow these steps: 

1. Log on to Administration Console as follows: 

a. Make sure that WebLogic Server is running. 

b. Start your favorite web browser. 

c. In the browser, type the URL of your server's Administration 
Console, athttp://localhost:7001/console. 

d. Type your username and password, and then click Sign In. 

For more information on using Administration Console, see Chapter 4. 

2. On the left side of the screen, click the Services folder, then click the 
JDBC folder, and then click the Connection Pools folder. 

A screen similar to the one in Figure 12-1 appears. If you previously con- 
figured any connection pools, they are listed instead, but you can still 
create another connection pool. 

3. Click the Configure a new JDBC Connection Pool link. 

The screen shown in Figure 12-2 appears. 

4. Enter the required information for your data source. 

The two most important pieces of information are the driver class name 
and the URL. Any database that you use with Java should provide these 
two values in the documentation. The values entered in Figure 12-2 are 
for the ODBC bridge driver, which enables you to access any ODBC- 
compatible driver for which you have a DSN. In a production environ- 
ment, you'd probably use Oracle, DB2, MySQL, or some other database. 

If you enter invalid data while setting up your connection pool, you 
won't receive an immediate error. Instead, an exception is thrown when 
you try to use the connection pool. 
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Connected to : localhosl 7001 | You are logged in as : admin | Logout 



Monitoring 



A JDBC connection pool contains a group of JDBC connections that are created 
when the connection pool is registered, usually when starting up WebLogic 
Server. Your application borrows a connection from the connection pool, uses it, 
then returns it to the connection pool by closing it. 

After creating a JDBC connection pool, you can create a data source or a 
transactional data source that applications can use to access the JDBC 
connection pool. 

When one or more JDBC connection pools are configured in the current 
WebLogic Server domain, this JDBC Connection Pools page displays key 
information about each of them. To create a JDBC connection pool, click the 
Configure a new JDBC Connection Pool... link. 

^ Configure a new JDBC Connection Pool,.. 
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Figure 12-2: 

Config- 
uring the 
connection 
pool. 
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Configure a JDBC Connection Pool 



Define and test connection 



Name your new connection pool and define connection properties. You 
can optionally test a database connection using the properties you 
define. 



Name! TestPool 
The name of this JDBC connection pool. 

Connection Properties 

Drivei Classname: sun.jdbc.odbc.JdbcOdbcDriver 



The full package name of JDBC driver class used to create the physical 
database connections in the connection pool. 

URL: jdbc:odbc:testdsn| 



< 



The URL of the database to connect to. The format of the URL varies by 
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5. Click Create. 

■-^ ^ ■ You might need to click the scroll bar to see the Create button. Little will 

1 1T\ f\ f \ l^c^^ige in the window. You'll know that you've successfully created the 

' >^ K-' >^ ' \fcimection pool by the fact that you can no longer change the name of 

the data source. 



Defining a data Source 

After you have a connection pool, you must attach it to a data source. It's 
through this data source that WebLogic accesses your database. By having 
the EJBs connect to data sources directly, you can quickly map data sources 
to other connection pools. This can be useful if you need to temporarily con- 
nect your application to a different database. 

To create a data source, follow these steps: 

Log on to Administration Console. 

For details, see Step 1 in the preceding section. 

On the left side of the screen, click the Services, JDBC, and then Data 
Sources folders. 

A screen similar to the one in Figure 12-3 appears. If you previously cre- 
ated any data sources, they're listed instead, but you can still create 
another data source. 

Click the Configure a new JDBC Data Source link. 

The screen shown in Figure 12-4 appears. 

Enter the required information for your data source. 

The two most important pieces of information are the data source name 
and the JNDI name. Administration Console uses the data source name 
to refer to your data source. Java programs and EJBs use the JNDI name 
to access your data source. Additionally, you must specify the name of 
the pool that this data source will reference, which is the pool that you 
created in the preceding section. 

If you enter invalid data while setting up your data source, you won't 
receive an immediate error. When you try to use your data source, 
however, an exception will be thrown. 

Click Create. 



1. 

2. 

3. 
4. 




5. 



After you create your data source, little will change in the window. You 
will know that the procedure worked by the fact that you can no longer 
change the name of the data source. 



Chapter 12: Accessing Data with JDBC 



«J Wel)Lo(jic Servei Console Microsoft Internet Explorer 




Figure 12-3: 

Getting 
ready to 
create the 
data source. 



File Edit View Favorites Tools Help 



t^Media 



bidebarFrameId=wl_consoleJrame_1049072950141&MBean=mydomain7o3AName7o3Dmydomain7o2CType7o3DDomain 



H mydomain 
B Cl Servers 
CJ Clusters 
CJ Machines 
S CJ Deployments 
□ '^3 Services 
CJjCOM 
B 3 JDBC 

CJ Connection Pools 
CJ MultiPools 
CJ Data Sources 
CJ Data Source Factories 
B CJ JHS 

B CJ Messaging Bridge 
CJXML 
O JTA 

bCJsnmp 
CJwtc 

CJWLEC (deprecated) 
CJ Jolt 

CJ Virtual Hosts 
□ Mail 
CJ FileT3 



I J*' 



Connected to : localhost 7001 



You are logged in as : admin 



A JDBC data source is an object bound to the JNDI tree that points to a JDBC connection 
pool or JDBC multipool. Applications can use a JDBC data source to get a database 
connection from a connection pool or multipool. 

When one or more JDBC data sources are configured in the current WebLogic Server 
domain, this JDBC Data Sources page displays key information about each of them. To 
create a JDBC data source, click the Configure a new JDBC Data Source... link. 
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mydomain> JDBC Data Sources> C 



Connected to : localhost 7001 



You are logged in as : admin | Logout 



Configure the data source 

Define your new JDBC data source. 



Name: MyJDBC Data Source 

The name of this JDBC data source. 



JNDI N.ime 



< 



The JNDI path to where this JDBC data source is bound. 
0 Honoi Global Transactions 

Specifies whether this data source will participate in existing global (XAl 
transactions. Unchecking this option while creating the data source 
should be done rarely and with care. This option can not be changed 
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Now you're ready to see whether your EJBs can access your newly created 
data source and connection pool. This topic is covered in the next section. 

DropBooks 

Using JDBC With EJBs 

In this section, you use the data source and connection pool that you just 
created. You implement a simple EJB that makes use of JDBC. I show you 
some of the most common ways that JDBC is used, providing examples of the 
following: 

v* Executing SQL statements 
Working with a result set 
I V Using prepared statements 

For this example, you need to create an EJB. I show you all the files necessary 
to create this EJB, but I don't go into the specific steps for compiling, deploy- 
ing, and executing this bean. For more information about those tasks, see 
Chapter 6. 

To properly compile this bean, you need a J2EE bean descriptor. Listing 12-1 
is the J2EE descriptor for the JDBC example. 

Listing 1 2-1 : J2EE EJB Descriptor 

<!D0CTYPE ejb-jar PUBLIC 

'-//Sun Microsystems, Inc. //DTD Enterprise JavaBeans 2.0//EN' 

'http://java.sun. com/dtd/ejb- jar_2_0 . dtd ' > 

<ejb-jar> 

<enterprise-beans> 
<sessi on> 

<e jb-name> JDBCSampl eObject</ejb-name> 

<home>com . dummi es . ejb . JDBCSampl eHome</home> 
<remote>com. dummi es.ejb.JDBCSample</remote> 
<ejb-class>com . dummi es .ejb. JDBCSampl eBean</ejb-class> 
<session-type>Stateless</session-type> 
<transaction-type>Container</transaction-type> 
</sessi on> 
</enterprise-beans> 
</ejb-jar> 

To compile the bean, you also need the WebLogic-specific bean descriptor. 
Listing 12-2 is the WebLogic descriptor for the JDBC example. 
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Listing 12-2: WebLogic EJB Descriptor 
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DOCTYPE weblogic-ejb-jar PUBLIC 

V\ Systems, Inc. //DTD WebLogic 6.0.0 EJB//EN ' 
r//www .bea.com/servers/wls600/dtd/ we blogic-ejb-jar.dtd'> 



<webl ogi c-ejb-jar> 

<weblogic-enterprise-bean> 

<ejb-name>JDBCSampl e0bject</e jb-name> 
<jndi -name>JDBCSampl e0bject</ jndi -name> 
</weblogic-enterprise-bean> 
</webl ogi c-e jb- j ar> 

Listing 12-3 is the home class that's compatible with the JDBC example. 
Listing 12-3: JDBC Sample Home Class 



package com . dummi es . ejb ; 






import javax.ejb.*; 
import Java . rmi .*; 






public interface JDBCSampl eHome extends EJBHome 
{ 




public JDBCSample createO 

throws Remote Except i on,CreateException; 

) 





Listing 12-4 is the bean interface that's compatible with the JDBC example. 

Listing 12-4: JDBC Example Bean Interface 

package com . dummi es . ejb ; 

import javax.ejb.*; 
import j ava . rmi . * ; 
import java . uti 1 . *; 

public interface JDBCSample extends EJBObject 
( 

public void executeO 
throws RemoteExcepti on ; 

public void preparedO 
throws RemoteExcepti on ; 

public Collection queryO 
throws RemoteExcepti on ; 
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Finally, Listing 12-5 is the complete bean implementation class. 
2-5: JDBC Example Implementation 



package com . dummi es . ejb ; 

import javax.ejb.*; 

import j a vax . nami ng . * ; 

import javax.sql .*; 

import Java . sql . * ; 

import Java . rmi . RemoteExcepti on ; 

import j ava . uti 1 . Vector ; 

import j ava . uti 1 .Enumeration; 

import Java . uti 1 .*; 



public class JDBCSampl eBean implements SessionBean 
{ 

private Sessi onContext stx; 

//Required methods, not used by this type of bean 
public void ejbCreate( ) { ) 
public void ejbRemove( ) { 1 
public void ejbActivateC ){ } 
public void ejbPassi vate( ) { ) 

// setter for the Sessi onContext 

public void setSessi onContext ( Sessi onContext ctx) 

{ 

ctx = this. stx; 



public void execute() 
throws RemoteExcepti on 

{ 

Connection conn = null; 
Statement statement = nul 1 ; 

try ( 

conn = getConnecti on ( ) ; 

String sql = "INSERT INTO t_student ( f_i d , fjfirst, 
f_last) VALUESd , ' John* , 'Smith* )" ; 

statement = conn . createStatement( ) ; 

statement . executeUpdate ( sql ) ; 
) catch ( Exception e ) { 

System.out.println(e); 
) finally { 

handleCleanup(conn,null .null .statement); 
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i c voi d preparedC ) 
.rows RemoteExcepti on 



Connection conn = null; 
Prepa redStatement ps = null; 

try { 

conn = getConnecti on ( ) ; 

String sql = "INSERT INTO t_student ( f_i d , f_first, 
f_last) VALUESC?, ?,?)"; 

ps = conn . prepareStatement( sql ) ; 

ps . set Int ( 1,1); 

ps.setString(2,"John"); 

ps . setStri ng( 3 , "Smi th" ) ; 

ps .executeUpdate( ) ; 
) catch ( Exception e ) I 

System . out . pri ntl n (" Error : " + e ); 
) finally { 

handleCleanup(conn,ps,null .null ); 



public Collection queryO 
throws RemoteExcepti on 

{ 

Connection conn = null; 

PreparedStatement ps = null; 

Resul tSet rs = null; 

Collection result = new ArrayListO; 

try { 

conn = getConnecti on () ; 

String sql = "SELECT f_id, f_first.f_last FROM 

t_student" ; 
ps = conn . prepareStatement( sql ) ; 
rs = ps .executeQuery( ) ; 

while( rs.nextO ) { 

result.add(rs.getString(3)); 



) catch ( Exception e ) { 
System . out . pri ntl n ( e ); 

) finally { 

handleCleanup(conn,ps,rs,null ); 



(continued) 
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Listing 1 2-5 (continued) 

return result; 



private Connection getConnecti on ( ) throws Nami ngExcepti on , 

SQLException { 
InitialContext ic = new I ni ti al Context () ; 
DataSource ds = 

(DataSource)ic.lookup("java:comp/env/jdbc/SchoolDa 

taSource" ) ; 
return ds . getConnecti on () ; 



private void handl eCl eanup( Connecti on 

conn , PreparedStatement ps,ResultSet rs , Statement 
statement ) 

{ 

// make sure the connection is returned to the connection 
pool 

try { 

if ( rs!=null ) 

rs . cl ose ( ) ; 
if ( statement ! =nul 1 ) 

statement . cl ose( ) ; 
if ( ps!=null ) 

ps . cl ose ( ) ; 
if ( conn!=null ) 

conn . cl ose( ) ; 
) catch ( SQLException e ) { 




Next, I will explain how this example was constructed, beginning with how you 
obtain a connection from a data source. If you're familiar with JDBC, you'll find 
that nothing is changed when you use JDBC from a WebLogic data source and 
connection pool, except the method by which you obtain the connection. 



Obtaining the connection 

To perform any database operation, you must first obtain a database connec- 
tion. This is a common process, so it will be placed in a method. This way, 
you won't have to duplicate the code everywhere that you need a connec- 
tion. This method will be named getConnecti on, as follows: 
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private Connection getConnecti on ( ) throws Nami ngExcepti on , 
SQLException { 
alContext ic = new Initial ContextC ) ; 
ource ds = 

(DataSource)ic.lookup("java:comp/env/jdbc/TestData 
Source" ) ; 
return ds . getConnecti on () ; 



The process for obtaining a connection using a WebLogic data source is 
easy. JDBC data sources are obtained through JNDI, a service that allows 
string-based names to be associated with services. First, an initial context is 
obtained; this gives you access to JNDI. Then the data source name is looked 
up using the java:comp/env/jdbc/TestData identifier. Although the data 
source has this lengthy name, you specify only the TestData name when set- 
ting up the data source. The comp/env/jdbc portion is added automatically. 
The Java: portion specifies the protocol; you should always use Java:. For 
more information about JNDI, refer to Chapter 13. 



Closing the data source 

When you're finished with a data source, you should release your data source 
back to the pool. The following method handles this task: 

private void handl eCl eanup(Connecti on conn , PreparedStatement 
ps.ResultSet rs, Statement statement) 

{ 

// make sure the connection is returned to the connection 
pool 

try { 

if ( rs!=null ) 

rs . cl ose( ) ; 
i f ( statement ! =nul 1 ) 
statement . cl ose( ) ; 
if ( ps!=null ) 

ps . cl ose( ) ; 
if ( conn!=null ) 
conn . cl ose ( ) ; 
) catch ( SQLException e ) { 
) 

) 

Connection, PreparedStatement, ResultSet, and Statement are passed 
in. If any of these values is not null, the close method is called on each one. 
SQLExcepti on errors are caught but ignored because you're closing the data 
source. 
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Executing an SQL statement 



ceding example, you executed a SELECT statement that returns 
INSERT, DELETE, and UPDATE SQL statements do not return data. 
These SQL statements are commands to alter the database, not requests for 
data. When you execute an INSERT, DELETE, or UPDATE command, you should 
execute the executeUpdate method, which doesn't expect data to be 
returned. The following code shows this: 



public void executeO 
throws RemoteExcepti on 

{ 

Connection conn = null; 
Statement statement = null; 



try 1 

conn = getConnecti on ( ) ; 

String sql = "INSERT INTO t_student(f_id, f_first, 
Oast) VALUES (1 , 'John' , 'Smith' )" ; 

statement = conn . createStatement( ) ; 

statement. executeUpdate (sql ) ; 
) catch ( Exception e ) I 

System.out.println(e); 
) finally { 

handleCleanup(conn,null , null , statement ) ; 

) 

} 



You begin by getting the connection. Next, the SQL statement is assigned to 
the sql String. A statement is created and the SQL is passed to the 
executeUpdate method. 

Note that John and Smi th are inserted directly into the SQL. Because these 
values will change, depending on what name you use, you should make them 
parameters. This will allow you to use the same SQL no matter what name 
you're inserting. This technique is shown in the next section. 



Using prepared statements 

A prepared statement allows you to insert parameters into an SQL statement. 
The following method uses a prepared statement named ps: 

publ i c void prepa red ( ) 
throws RemoteExcepti on 

( 

Connection conn = null; 
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getConnecti on ( ) ; 
ring sql = "INSERT INTO t_student(f_id, f_first, 
f_last) VALUES(?, ?,?)"; 
ps = conn . prepareStatement( sql ) ; 
ps . setlntC 1 , 1 ) ; 
ps.setString(2,"John"); 
ps . setSt ri ng ( 3 , " Smi th" ) ; 
ps . executeUpdate ( ) ; 
I catch ( Exception e ) I 

System . out . pri ntl n (" Error : " + e ); 
) finally { 

handleCleanup(conn,ps,null , null ); 



} 



This method starts out like the one before it. A connection is obtained and an 
SQL is specified. Note, however, that this SQL includes question mark values. 
These are parameters that will be added later by using the set methods of 
the prepared statement. 

If you use prepared statements, make sure that you've set the values of all 
specified parameters. Otherwise, you'll get an error. 

Submitting a query 

A query is an SQL statement that returns data. The following code performs a 
query: 




public Collection queryO 
throws RemoteExcepti on 

{ 

Connection conn = null; 

PreparedStatement ps = null; 

Resul tSet rs = nul 1 ; 

Collection result = new ArrayListO; 

try { 

conn = getConnecti on () ; 

String sql = "SELECT f_id, f_f i rst,f_l ast FROM 

t_student" ; 
ps = conn . prepa restatement ( sql ) ; 
rs = ps . executeQuery ( ) ; 



while( rs.nextO ) { 
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} finally { 



handleCleanup(conn,ps,rs,null ); 

) 

return result; 



This code uses PreparedStatement as well. A sel ect statement retrieves 
all the data from the table. To move through the returned data, you use a 
result set named Resul tSet. This result set allows you to access the rows 
and fields of the database being returned. The next method of Resul tSet is 
used to move to the next row and also to verify that more data is coming. 
This method copies every last name into a collection of strings. 



Monitoring JOBC 

One problem with connection pools is that they may have too many 
requested connections to be effective. If you're not aware of the number 
of requested connections, you should monitor the current state of your con- 
nection pools. 




You monitor only at the connection pool level. You can't monitor at the data 
source level. 



To monitor your connection pool, follow these steps: 

1. Make sure that your connection pool and data source are set up and 
targeted to the correct server. 

2. Make sure that your server is running, and then log on to 
Administrative Console. 

For details on logging on, see the "Creating a Connection Pool" section. 

3. On the left side of the screen, click the following folders: Services, 
JDBC, Connection Pools, and then SchoolPool. 

4. Click the Monitoring tab. 

The screen shown in Figure 12-5 appears. From this screen, you can 
monitor the usage of your connection pool. 
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Figure 12-5: 
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Chapter 13 



In This Chapter 

Figuring out what JNDI is 

Listing an EJB in the JNDI phone book 

Finding an EJB in the JNDI phone book 



/3 pplication servers, such as WebLogic, allow you to provide Enterprise 
¥ • Java Beans (EJBs) to client programs that are often running on computers 
other than the application server. These EJBs do the client programs no good if 
the client can't find them. In this chapter, I explain what you need to do so that 
your client programs can find the EJBs made available through WebLogic. 

This is not a complex process. In fact, the process that a client program uses 
to find an EJB is similar to the process that you use to find the phone number 
to a pizza parlor: You look it up in a directory. Just as the phone book enables 
you to connect a pizza parlor's name with its phone number, JNDI (Java 
Naming and Directory Interface) enables your client programs to connect EJB 
names with the more technical and difficult-to-remember numbers that the 
program needs to find and use the EJBs. 

In this chapter, you find out how to do two important tasks that enable your 
client application to find and use EJBs: 

Making resources available with JNDI 
V Finding resources with JNDI 

As a WebLogic administrator, you'll become pretty familiar with these two 
tasks. WebLogic also uses JNDI with JMS (Java Message Service), which is 
covered in Chapter 15. 




WebLogic administrators use JNDI to help others locate the EJBs stored on 
WebLogic Server. That is the main purpose of JNDI — to locate Internet 
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resources, such as EJBs. Locating a resource based on its name is an impor- 
tant function of the Internet. Every time you use a browser to access a web 
k 're using a network name resolution system. The host name of the 
at you're trying to access must be translated from a human readable 
name (such as www .yahoo . com) to an IP address that the computer uses to 
access the web site. 



JNDI is a specification that Sun created for Java to standardize network name 
resolution. Rather than having a variety of different interfaces for different 
name resolution systems, JNDI gives you one standard application program- 
ming interface (API) to program to. In this way, programmers don't have to 
waste time learning new interfaces to network name resolution software. 

Many books about JNDI explain how to create your own JNDI-compatible 
interface for your applications. In this book, however, you find out how to use 
a JNDI interface, in particular the JNDI interface in WebLogic. 




JNDI is more of a protocol than an actual program. Sun has defined a stan- 
dard way for directories to work and any directory that adheres to this stan- 
dard can be said to be JNDI compliant. 



JNDI makes available two primary services: 

If Naming service. Allows names to be used to locate and retrieve objects. 
Directory service. Allows attributes to be specified and a search to be 
performed. 

To understand the differences between the two, it helps to think of how you 
use a phone book. The naming service is similar to the white pages, which 
you use to look up a person or business when you know the exact name. The 
directory service resembles the yellow pages, which you use when you know 
what sort of a business you're looking for but don't know the exact name. 
You look up a category, such as plumbing or picture framing, and then skim 
the yellow pages looking at the advertisements and find one that most 
closely matches that attributes that you're looking for. 



Understanding JNbl names 

You use a JNDI name to reference an EJB. A JNDI name has no preset format, 
but it does follow a few rules. The name must start with a letter. The rest of 
the name can contain periods, hyphens, numbers, and letters, for example, 
My EJBCol 1 ecti on . My IstEJB. Now that you understand the format of a JNDI 
name, you're ready to begin using EJBs that have JNDI names. 
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servers using Java. This means that if a Java 
program is written to be compatible with JNDI, 
this program is compatible with any other 
naming system that is also compatible with JNDI. 

Name services are common on the Internet. You 
use a name service (DNS, or domain name ser- 
vice) every time you launch your browser and 
reach a web page. 

If you open a browser and enter the URL 
www. dummies .com, for example, you are taken 



to the For Dummies home page. To find this page, 
you remembered a uniform resource location, or 
URL. This is just a fancy term for a name entry in 
a DNS. But this is not the actual site address that 
the computer uses. The actual address to this 
site is the IP address 208.215.179.139. DNS 
enables you to remember www . dummi es . com 
rather than the much longer IP address. The 
naming service takes care of translating 
between the two. 



JNDl as a universal naming service 

DNS is only one of many naming services available on the Internet. The com- 
mands to use naming services vary greatly from one service to the next. There 
is already enough to learn without having to learn the idiosyncrasies of indi- 
vidual name services. This is where JNDI comes in to make life easier. 

JNDI provides a common programming interface to access different name 
services. You have to understand only one programming interface to use 
many services. Table 13-1 summarizes some of the common services that 
JNDI gives you access to. 



Table 13-1 Common Services Available Through JNDI 



Abbreviation Name 



COS Common Object Services 



DNS Domain Name Service 



What It Does 

Accesses CORBA resources, which 
are an alternative to EJBs. When 
using WebLogic, you usually use 
EJBs over CORBA resources. 

Looks up the IP address for 
addresses, such as www. 
dummi es . com. 

(continued) 



222 P art The Forgotten Services 



Table 13-1 (continued) 



DropBoo^ 



iation Name 



What It Does 



NIS 



Lightweight Directory 
Access Protocol 



Accesses named Internet resources. 
LDAP is an alternative to DNS 
developed by the University of 
Michigan and endorsed by more 
than 40 companies. 



Network Information System 



Accesses named Internet resources. 
NIS is an alternative naming service 
developed by Sun Microsystems. 



Implementing JNbt Using WebLogic 

WebLogic is fully compliant with the JNDI standard, which means that any 
Java program designed to work with JNDI can be used also with WebLogic. 
To be compliant with JNDI, WebLogic must: 

IV Allow client programs to access WebLogic name services 
V Allow client programs to access WebLogic objects 

By using the WebLogic implementation of JNDI, you can allow your WebLogic 
resources to be accessed from client programs running on other computers. 
As long as a client program knows the name that your WebLogic resource is 
listed under, the program can find the resource. 

In this section, you find out how to configure WebLogic to make your objects 
available through JNDI. Then you find out how to access these objects from 
Java programs. 



Making WebLoqic resources aVaiiabie 
through JNbl 

Before other programs can use your WebLogic objects, you must make those 
objects available. This step is similar to adding a person's name to a phone 
book. When you add a WebLogic object to the JNDI directory, you associate 
the name of the object with the object itself. 
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The objects that you make available through JNDI are called Enterprise Java 
Beans (EJBs). If you need more information on how to obtain or construct 
sr to Chapter 6. This chapter assumes that you already have an EJB 
iwant to make available under a JNDI name. 
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EJBs are made up of regular Java classes and configuration files. Like any 
other Java class, the class files must be in the correct directory so that 
WebLogic (in this case) can find these files and allow your EJB to be used. 
You must place the class files to be used with an EJB in the W E B - 1 N F / 1 i b 
directory. (For more information on this directory, see Chapter 5.) 

The WEB-INF/lib directory is hidden to Internet users accessing your server, 
so it's safe to place files such as an EJB file there. It would be a security risk if 
an Internet user were able to download your EJB file and examine it. 

To add an EJB, you can use WebLogic Workshop, which is a development tool 
that can help set up EJBs Here's an overview of adding an EJB to WebLogic 
using WebLogic Workshop: 

1. Make sure that your EJB class files have been copied to WEBINF/lib. 

2. Start WebLogic Workshop. 

3. Choose Add EJB from the Designer pull-down menu. 

4. Enter the required information. 

5. Restart WebLogic. 



Now that you know generally how to assign a JNDI name to an EJB, you're 
ready to dive in. Follow these steps: 



1. Place your EJB class files in the WEBINF/lib directory. 

On a Windows system with a typical installation of WebLogic, this direc- 
tory is usually the following or something similar: 

c : \bea\webl ogi c81\sampl es\ works hop \ Your Appl i cati on 

In Figure 13-1, you can see the files that make up the EJBs that this 
instance of WebLogic Server is using. EJBs are usually distributed as 
Java archive files, which have the file extension .jar. You should place 
your .jar file in the 1 i b directory. 

2. Start WebLogic Workshop. 

WebLogic Workshop enables you to add an EJB to your application 
server. If you need help starting WebLogic Workshop, see Chapter 11. 

3. Choose InsertOControlsOAdd EJB Control. 

The screen shown in Figure 13-2 appears, providing many additional 
configuration options. Note that the Insert EJB Control dialog box is 
divided into three steps. 
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Insert Control - Insert EJB Control @ 

STEP 1 variable name for this control: | MyEJB | 

STEP 2 I would like to : 

O Use an EJB Control control already defined by a JCX file 



® Create a new EJB Control control to use. 



New JCX name: MyEJB 



O Make this a control factory that can create multiple instances at runtime 



Figure 13-2: 

The EJB 
configu- 
ration 
window. 



STEP 3 This EJB control finds the EJB with this JNDI name 
jndi-name: I MyEJB 



This EJB control uses the following interfaces 
home interface: 
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4. In the Step 1 section, type a variable name to reference the EJB in 
WebLogic. 



5. In the Step 2 section, choose to use an EJB control or create an EJB 



If you've already worked with this EJB and created a control file, specify 
the file that you would like to use. If you're using a new EJB, choose to 
create an EJB control. 

6. In the Step 3 section, type the JNDI name and the class names. 

a. In the jndi-name box, type the JNDI name that other applications 
use to access this EJB. 

Use a name that is meaningful to your application and that is not 
duplicated by a similar resource. The name can contain periods, 
hyphens, numbers, and letters, but it must start with a letter. 

b. In the home interface box, type the name of your EJB's home class. 
In the bean interface box, type the name of your EJB's bean class. 

The home and bean interface boxes allow you to specify the exact 
classes used for this EJB. EJBs always have both a home and bean 
class. The documentation provided with your EJB should list the 
home and bean name for the EJB. 

7. Restart WebLogic Server. 

You have to restart the server because you added a bean. After 
WebLogic Server has been restarted, your EJBs are available. 

Congratulations! You've finished the first part of the process. In the next sec- 
tion, you delve into the second part. 



Enabling JNbl to access WebLogic objects 



When you create EJBs and make them available with WebLogic Server, other 
applications access the functionality of these objects. In this section, you find 
out how to use JNDI to access your WebLogic objects from other programs. 
The process is summarized as follows: 

1. Set up the Ini ti al Context object. 

2. Look up the required named object. 

3. Use the remote object. 




name should describe your EJB and should be unique. 



control. 



4. Complete the session. 
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Set up InitiatContext 

Finpt, you obtain an Ini ti al Context object by providing information about 
TliL^b©t you're seeking. This information is passed to the I ni ti al Context 
•«bJe\fSiKing a hash table. After this table has been constructed, it's passed to 

the constructor of the Ini ti a 1 Context object. Listing 13-1 shows this process. 

Listing 13-1: Obtaining an initialContext 
Context context; 

Hashtable hashTable = new HashtableO; 

hashTabl e . put( 

Context. INITIAL_CONTEXT_FACTORY , 

"webl ogi c . jndi . WLI ni ti al Context Factory ") ; 
ha shTable. put ( Context. PROV I DER_URL, 

"t3://localhost:7001") ; 

try 

context = new InitialContext(ht) ; 
catch ( Nami ngExcepti on e) 

System . out . pri ntl n (" Error : " + e ); 
final ly 

try 

{ 

context . cl ose( ) ; 

) 

catch (Exception e) 

{ 

System . out . pri ntl n (" Error : " + e); 



Ajava.util .Hashtable obj ect is used to organize a collection of name- 
value pairs. You can put any number of values into HashTabl e. Each value 
is located using a name. For example, in the preceding code, the name 
Context. INITIAL_CONTEXT_FACTORY is used to store the value "webl ogi c. 
jndi.WLInitialContextFactory". This allows JNDI to accept the following 
parameters to control its operation: 

j avax. naming. Context. IN ITIAL_CONTEXT_FACTORY. To access 
WebLogic, set this parameter to webl ogi c . j ndi . WLI ni ti al 

ContextFactory. 
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javax. naming. Context. PROVIDER_URL. This property specifies the 
URL of the WebLogic Server that provides the name service. The default 
his property ist3://localhost:7001. 

catch statements in Listing 13-1. The catch statements contain 
blocks of code. If any error causes an exception to be raised, the program 
immediately executes the catch block. 

Look up the named object 

Now that you have a context object, you can attempt to look up the object 
that you need. Listing 13-2 shows a way to look up a named object. 

Listing 13-2: Looking Up a Named Object 

try 

ServiceBean bean = 

(ServiceBean)context.lookup("ejb.serviceBean"); 

catch ( NameNotFoundExcepti on e) 

System . out . pri n 1 1 n (" Error : " + e ); 
catch ( Nami ngExcepti on e) 

System . out . pri ntl n (" Error : " + e ); 



An EJB named ejb.serviceBean is looked up. Two catch blocks handle two 
types of errors that can occur. The first, NameNotFoundExcepti on, occurs 
when an invalid EJB name has been specified. The second, Nami ngExcepti on, 
handles more generic errors that may occur during the lookup, such as an 
I/O error. 

Use the remote object 

You're now ready to instantiate an EJB based on the object that you requested, 
as shown in Listing 13-3. After you allocate this EJB, you can call the method 
provided by the bean. 

Listing 13-3: Using the Remote Object 

ServiceBean bean = 

ServiceBean. Home .create("ejb.ServiceBean"); 

bean.remoteMethod( "some parm" ) ; 
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An EJB named ejb . Servi ceBean is loaded, and then the remoteMethod 
method is called and passed a string. You're now free to use the bean as you 
ly other Java bean. When you're finished with this bean, you should 
i connection. 

This step is where you perform the work that you originally set out to do. 
Often this step includes many calls to the remote bean. Calling Java beans 
is similar to calling methods in regular classes. 

One of the main features of beans is that they isolate you from what is going 
on. All you have to do is call your bean object, just like you'd access any 
other properly formatted object. A lot is going on in the background, as the 
request is routed from one computer to the next using EJB and RMI. Usually, 
you don't need to worry about the exact file formats. 

Close the connection 

When you're finished with the object, you need to close it. This frees up any 
resources that this object was using. This can be seen in Listing 13-4. 
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Listing 13-4: Closing the Connection 




final ly 




try 
{ 






context . cl os 


e(); 




i 

catch (Exception e) 




{ 

System . out . pri ntl n (" Error : " + e ); 




i 

) 





It's a good idea to put the context close inside a f i na 11 y block. That way, 
you can be assured that the close was actually called. 

If any exceptions are thrown by this operation, they're caught by catch. After 
a context has been closed, it should not be reused. 




You should close the connection when you're finished with it. A common mis- 
conception is that Java does this for you. Although Java frees the memory 
associated with the bean, it doesn't free up any resources that have been 
allocated to the bean. This can lead to incomplete results because the bean 
was never given a chance to properly exit. Additionally, not calling the close 
method causes these resources to never be freed. If this practice continues, 
you eventually run out of resources and must restart your application server. 
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In This Chapter 

Understanding transactions and when to use them 
Finding out about bean-managed transactions 




rransactions are a way to logically group database commands, so that 
all commands are processed as a group. If any single command in the 
transaction fails, all the other commands fail as well and the effects of those 
commands are "rolled back." 

When a transaction is presented to WebLogic, one of two actions will occur: 
a commit or a roll back. When a transaction is committed, the changes to the 
database are made permanent. When a transaction is rolled back, the changes 
to the database are discarded. In this chapter, you discover the basics of using 
WebLogic transactions and find out when you should and shouldn't use them. 



Transactions, which are a fundamental feature of WebLogic, allow database 
changes to be completed accurately and reliably. These transactions are 
based on the ACID (atomicity, consistency, isolation, and durability) proper- 
ties for high-performance transaction processing: 

v* Atomicity. Changes that a transaction makes to a database are made as 
a single unit. One failure results in the total failure of the transaction. 

V Consistency. The database was valid before the transaction and will 
remain valid after the transaction. The database may never enter an 
invalid state. 

f Isolation. As one operation performs a transaction, the transaction is vis- 
ible to no other operations until the transaction completes successfully. 



Understanding Transactions 



t<" Durability. A change to the database will survive future system or media 
failures. 
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ACID ensures that database updates are performed as intended: completely 
and accurately. To understand why this is important, consider a simple bank 
in which you move $100 from your checking account to your money 
count. This transfer requires several database transactions: 



1. Remove $100 from your checking account. 

2. Add $100 to your money market account. 

3. Add a line to the general ledger to reflect these transactions. 

Each operation represents one or more separate database commands. 
Consider if Step 1 failed and the operation aborted with only Step 2 complete. 
The bank would have added $100 to your money market account, without 
having adjusted your checking account. The bank would lose $100. 

Transactions allow all three steps to execute as a unit. If one step fails, they 
all fail. Additionally, no other operation can access the results of this change 
until all three steps are complete. 

^i-STOjf WebLogic's transaction implementation relies on Java Transaction Architecture 
" ' (JTA), a standard developed by Sun Microsystems. JTA specifies standard Java 
interfaces between the transaction manager, the resource manager, the applica- 
tion server, and transactional applications. 




Tu/o-phase commit 

WebLogic uses transactions to guarantee that a single database server main- 
tains its integrity even if part of the transaction fails. A single database 
server, however, is not always the case. 

Database servers can be clustered to allow more than one database server to 
function as a single logical database server. This arrangement has several 
advantages: 

Scalability. If one database server becomes overworked and impedes 
system performance, another database server can be added to the cluster. 

Reliability. If one database server crashes, the other database servers 
increase their load to account for the failed server. 

Performance. If your application runs at several geographic locations, 
each location can have a local server. This improves performance for 
read operations. Write operations synchronize among the databases. 

To support distributed database access, WebLogic makes use of something 
called a two-phase commit. The two-phase commit allows data to be written 
to two or more databases while keeping both databases in sync. 
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Following are the participants of a two-phase commit: 

J^Ra^overable resource. Provides permanent storage for data. The recov- 
fte^9fr>le resource is almost always a relational database. 

V Resource manager. Provides access to a collection of information and 
processes. The resource manager is almost always a transaction-aware 
JDBC driver. 

f" Transaction manager. Manages transactions for application programs. 
This is the role that WebLogic plays. 

W Transaction originator. Uses the transaction services. The transaction 
originator can be an application, an Enterprise JavaBean, or a JMS client. 

In the two-phase commit process, a transaction originator seeks to update a 
number of recoverable resources. As its name implies, the two-phase commit 
has two main steps: 

v 0 Prepare phase. During the prepare phase, the required updates are saved 
in a transaction log file. The resources must "vote" on whether to commit 
or roll back the changes. 

f Finalization phase. The transaction manager evaluates the votes. If all 
resources have voted to commit the changes, the changes are commit- 
ted. If even one resource votes not to commit the changes, they are 
rolled back to their previous state. 

As you can see, the two-phase commit is essential when using multiple 
databases. 



When to use transactions 

Like any technology, transactions are not a silver bullet designed to be used 
in all cases. Knowing when to use transactions is just as important as know- 
ing when not to use them. In this section, I describe a few examples that 
should use transactions. 

Transactions across multiple databases 

The first model where a transaction is likely appropriate is when the client 
application must perform operations on several objects stored in one or 
more databases. If any one command is unsuccessful, the entire transaction 
is rolled back. 

For example, suppose that an insurance company has several branch offices, 
each of which has a database server. When a new policy is issued, this trans- 
action is added to the database server at each branch office. If one of the 
database servers fails to update, the entire transaction fails. 
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Accumulation transaction 

The second model where a transaction is likely appropriate is when the client 



n must communicate several times with a server object. The server 
e^t^sCcumulates these transactions and updates the database at some 
point in the future, not on every communication with the client. Examples of 
this situation include the following: 



I 



f" Data is stored in memory or written to a database each time the server 
method is called. 

v 0 Data is written to the database at the end of several exchanges with the 
client application. 

The server object needs to maintain the data from each invocation of 
its method and write the contents to a database at the end of the 
conversation. 

The client application needs a way to cancel all previous communication 
with the server object. 



Each of these scenarios shares one similarity: committing the data to the data- 
base is the last event to happen. Each stage accumulates data, but doesn't 
actually apply the changes to the full database until the final commit. 

An example of this model is a shipping application in which the server object 
is called several times to add items to the shipping list. The server method is 
called for each item that is added. If one item fails to be added to the list, the 
entire shipping list is rejected. 

Multipart transaction 

The third model where a transaction may be appropriate is when only a 
single call is made to the server object, but the server object must make sev- 
eral database calls to carry out the request. Because the transaction occurs 
in several calls, it's called a multipart transaction. If one of these database 
calls fails, the entire transaction fails. 

An example of this was discussed earlier in this chapter. A user wants to move 
$100 from a checking account to a money market account. To be successful, 
this transaction must decrease the checking account by $100, increase the 
money market account by $100, and make an entry in the general ledger. If one 
of these steps fails, the entire transaction fails. 



When not to use transactions 

Perhaps the biggest problem with transactions is that they are all or nothing. 
You can't partially roll back a transaction. Your business application may rep- 
resent a chain of events, where a failure will likely occur at some point. If you 
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would like your data to be made permanent up to this point, a transaction is 
not a good choice for your application. 



a shopping cart program that uses the accumulation model. As items 
are added to the shopping cart, a failure may occur if an item is not recognized. 
This failure may be acceptable because the customer may be willing to accept 
a partial order. 



Using Transactions 

Using an EJB with transactions involves the following process: 

1. Import packages. 

2. Use JNDI to return an object reference. 

3. Update the database. 

4. Start the transaction. 

5. Complete the transaction. 

These same steps allow you to use your transaction connection also with an 
RMI application. 

The example in this section uses the UserTransacti on object for bean- 
managed transaction processing. 




Importing packages 

First, you must make sure that you import the correct classes. The following 
import statements must appear at the top of the class that will make use of 
transactions: 



import j avax . nami ng . * ; 

import j avax . transact!' on . 

import j avax . transact!' on . 

import j avax . transacti on . 

import j avax . transacti on . 

import j avax . transacti on . 

import j avax . transacti on . 

import j avax . transacti on . 

import j avax . transacti on . 



UserTransacti on ; 
SystemExcepti on ; 
HeuristicMixedException; 
Heuri sti cRol 1 backExcepti on ; 
Not Supported Except i on ; 
Rol 1 backExcepti on ; 
Illegal Sta te Except i on ; 
Securi ty Excepti on ; 



And if any class itself requires other classes, be sure to import those as well. 
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Some of the previously listed import statements reference classes that are 
part of J2EE. Because of this, make sure that the J2EE JAR file is part of your 
C^l^^j~H. For more information on setting up J2EE, refer to Chapter 2. 

Using JNbl to return an object reference 

After you import the correct classes, you're ready to use JNDI to obtain a 

UserTransacti on object. 

In this section, you use JNDI to return an object reference. First, you create a 
hash table that will contain the parameters used to create the object reference: 



Context ctx = null; 

Hashtable env = new Hashtabl e ( ) ; 



After you create Hashtable, you fill it with the appropriate configuration 
information. First you specify the class name for the context factory. You 
always specify this class when using transactions: 

// Parameters for WebLogic Server 
env. put (Context. IN ITIAL_CONTEXT_FACTORY , 
"webl ogi c . j ndi . WLIni ti a 1 Context Factory " ) ; 

Next, you must specify the security provider, which is 1 3 : / / 1 o c a 1 host:7001 
when using WebLogic. You must also specify your user ID and password: 

env. put (Context. PRO V I DERJJRL, "t3 : //l oca 1 host : 7001 ") ; 

env.put(Context.SECURITY_PRINCIPAL, "user" ) ; 

env. put ( Context. SECURITY_CREDENTI ALS , "password" ) ; 

After you've filled Hashtable with the required information, you're ready to 
create your Context: 

ctx = new InitialContext(env) ; 
UserTransacti on tx = ( UserTransacti on ) 
ctx. lookup("javax. transact ion. UserTransacti on"); 

The javax. naming. Context object allows you to access a JNDI name. At 
this point, you have access to a UserTransacti on object, which will be used 
to work with your transactions. 



Starting the transaction 

Now that you have a UserTransacti on object, you can start your trans- 
action. The transaction begins by calling the begi n ( ) method of the User 
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Transact!' on object. Any database operation that occurs after the begi n ( ) 
method invocation and before the transaction completion is considered part 
f Ihte^tijansaction. The following lines of code begin the transaction: 



UserTTansacti on tx = ( UserTransacti on ) 

ctx. 1 ookup( "javax. transact ion. Use rTransact ion"); 
tx .begi n ( ) ; 

At this point, you may carry out the database commands that are considered 
part of the transaction. After you complete the necessary database transac- 
tions, you're ready to complete the transaction. 



Updating the database 



At the heart of a transaction is the database update. First, you need to obtain 
a database connection. This connection is a regular JDBC 

Java . sql . Connecti on object: 

Connection connection; 

Next, you obtain the connection. Because it is possible for exceptions to be 
thrown during this process, you place this code in a t ry block: 

try { 

Driver driver = (Driver) 
Class. forNa me ("weblogic.jdbc.jts.Driver").newInstance(); 

This code obtains a JTS-capable driver from WebLogic. This driver will be 
used to access your Tx connection pool. 

A connection is obtained by specifying the name of the Tx data source that 
you created earlier, which is the data source named MyTxPool : 

connecti on = dr i ver . connect ( " j dbc : we bl ogi c : jts : MyTxPool ") ; 

You can now begin your transaction: 

tx .begi n ( ) ; 

Next, you build your SQL statement. The SQL statement shown here updates 
the database used in Chapter 12: 

String sql = "INSERT INTO t_student(f_id, f_first, f_last)"; 
sql +=" VALUESC 1 , ' John ',' Smith ')" ; 
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Now that the SQL has been prepared, you assign a statement from your driver: 

•talent statement = connecti on . createStatement( ) ; 

is executed with a call to executeUpdate: 

statement . executeUpdate ( sql ) ; 

Next, you can close the statement and commit the transaction: 

statement . cl ose( ) ; 
tx . commi t ( ) ; 

Now you close the connection and handle any exceptions: 



connecti on . cl ose( ) ; 




catch( Exception e) 






{ 

e.printStackTraceO; 

) 







In many languages, memory leaks and resource leaks are common problems. 
A leak occurs when a program allocates a memory or resource object and 
never returns it. Although Java will not leak memory, it can leak resources. 
Because of this, you should always close your database objects. Leaving 
them open can cause WebLogic to run out of database resources. 

To properly close all database resources, it's often useful to implement a 
cleanup method and include that method in a f i na 1 1 y clause. You can then 
close the database resources in the finally clause. Such a method is shown 
in Chapter 8. 

After you update the database, you're ready to complete the transaction. 
The code just examined completed its transaction with a call to commi t ( ) . 
However, this is not the only way a transaction is completed, as covered in 
the next section. 



Completing the transaction 

When completing a transaction, you can either roll back or commit your 
transaction. When you roll back a transaction, no permanent changes are 
made to the database. To roll back a transaction, call the rol 1 back( ) 
method of the UserTransacti on object: 



tx. rol 1 back( ) 
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When you commit a transaction, all changes are written to the database. To 
commit a transaction, use the commi t ( ) method of the UserTransaction 




Both the r o 1 1 b a c k ( ) and c o mm i t ( ) methods may throw an exception during 
execution. If the rol 1 back( ) method throws an exception, the data is not 
written to the database. 

If an exception occurs while the commi t method is called, the update does not 
occur. Exceptions can happen for many reasons. In a distributed database, all 
underlying databases must agree to the commit for it to be successful. 
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Chapter 15 

^ 5en§ing Messages Between 
Programs with JMS 



In This Chapter 

Accessing WebLogic's message service 
Using the point to point domain 
Using the publish subscribe domain 
Administering and monitoring messaging 



Software components can use many different methods to communicate 
with each other. In this chapter, I show you a model for the exchange of 
information between software components. This system is Java Messaging 
Service, or JMS. 

JMS clients connect to a JMS-compatible messaging server, such as WebLogic 
JMS (a component of WebLogic Server). A messaging server, such as WebLogic, 
provides facilities for sending and receiving messages. A JMS client can send 
messages to, and receive messages from, any other JMS client. You can think 
of the messaging service as the low-level infrastructure. The messaging 
service delivers a message from one program to another. The messaging ser- 
vice doesn't get involved in the contents of the message. It only facilities the 
message's transfer. 

One of the main differences between JMS and other models that software com- 
ponents use to communicate is that JMS is asynchronous. In an asynchronous 
model, a component simply sends a message to a destination. The message 
recipient can then retrieve these messages from the destination. No direct 
communication exists between the sender and the receiver. The sender knows 
only that a destination exists to which it can send messages. Likewise, the 
receiver knows only that a destination exists from which it can receive mes- 
sages. As long as both sender and receiver agree upon a common message 
format, the messaging system manages the message delivery. 
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Common concerns when working with asynchronous message systems are 
reliability and acknowledgement. If a message is sent from sender to receiver, 
equired response, how can the sender know that the message was 
ent? The specific level of reliability is typically configurable on a 
per-destination or per-client basis. However, messaging systems are capable 
of guaranteeing that a message is delivered — and delivered to each intended 
recipient exactly once. 



WebLogic supports two styles of message-based communications: 



V Point-to-point messaging. Point-to-point messaging is provided using 
JMS queues. A queue is a named resource configured in a JMS server. 
A JMS client exchanges messages with this queue. 

Point-to-point messages have a single consumer: the Java program that 
processes the messages. Multiple receivers may make use of the same 
queue as they listen for messages. However, after any receiver retrieves 
a message from the queue, that message is "consumed" and no longer 
available to other potential consumers. 

The message consumer must acknowledge receipt of every message it 
receives. This is because the messaging system continues attempting to 
resend a particular message until the message is retrieved. However, the 
sender does not resend the message indefinitely. The message is no 
longer sent after a predetermined number of retries. 

Publish-and-subscribe messaging. Publish-and-subscribe messaging is 
accomplished using JMS topics. A topic is a named resource configured in 
a JMS server. A JMS client publishes messages to a topic or subscribes to 
a topic. Published messages may have multiple subscribers. All current 
subscribers to a specific topic receive all messages published to that 
topic after the subscription becomes active. 



Creating a WebLogic Message Service 

Before you can create JMS senders and receivers, you must create a message 
service on your WebLogic Server. This process has a number of steps: 

1. Create a connection factory. 

A connection factory is used to grant connections to your messaging 
service. The connection factory is identified by a JNDI name. 

2. Optionally define backing stores for your messages. 

WebLogic needs to store incoming messages. You can store these mes- 
sages using a JDBC database or disk-based files. (Backing stores, which 
allow incoming messages to be stored until processed, are discussed 
later in this section.) 
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3. Optionally define destination keys. 

k Destination keys are a WebLogic extension to JMS that allows you to 
c©trol the order in which messages are delivered. 



4. Optionally define templates. 

Template keys are a WebLogic extension to JMS that allows you to group 
destinations. This gives you the ability to send messages to the group. 

5. Create a JMS server. 

A JMS server contains your queues and topics. If you created an optional 
backing store, the JMS server routes your messages there as well. 

6. Create one or more queues or topics. 

Queues or topics are mapped to your JMS server. Your clients, the 
senders and receivers, communicate with these queues and topics. 

The following sections discuss how to set up a WebLogic message service 
using these steps. 



The first step in creating a message service is to create a connection factory. A 
connection factory is an object used to create connections. Client programs use 
the connection factory to access the JMS message service. Follow these steps: 

1. Log on to Administration Console. 

This allows you to configure your transactions. Administration Console 
is typically athttp://localhost:7001/console. For more informa- 
tion, see Chapter 4. 

2. On the left side of the screen, click the following folders: Services, 
JMS, and then Connection Factories. 

The screen shown in Figure 15-1 appears. From here, you can see all cur- 
rent connection factories (if any) and create connection factories. 

3. Click the Configure a new JMS Connection Factory link. 

The screen shown in Figure 15-2 appears. 

4. Configure your connection factory. 

To follow along with the example, set the name and the JNDI name as 
shown in Figure 15-2. Leave the other values as is. For a description of 
all connection factory settings, see Table 15-1. 

5. Click Create. 




Creating a connection factory 



You now have a connection factory. 
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Connected to : localhost 7001 



You are logged in as : admin 



Connection factories are objects that enable JMS clients to create JMS connections. A 
connection factory supports concurrent use, enabling multiple threads to access the 
object simultaneously. After defining a JMS server, you can configure one or more 
connection factories to create connections with predefined attributes. 

When one or more JMS connection factories are configured in the current WebLogic 
Server domain, this JMS Connection Factories page displays key information about each 
of them. To create a JMS connection factory, click the Configure a new JMS Connection 
Factory... link. 

[^ Configure a new JMS Connection Factory... 
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mydomain> JMS Connection Factories> Create a new 
JMSConnectionFactory... 

Connected to : localhost 7001 I You are logged in as : admin 




Target and Deploy | Notes 
I General | Transactions | Flow Control 

This page allows you to define the general configuration of this JMS connection 
factory. 



& Name: 



MyConnection Factory 



The name of this JMS connection factory. 
& JNDI Name: MyConnectionFacfory 



The JNDI name used to look up this JMS connection factory within the 
JNDI namespace. 



Client ID: 



< 



An optional client ID for a durable subscriber that uses this JMS 
connection factory. Configuring this value on the connection factory 
prevents more than one JMS client from using a connection from the 
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Table 15-1 


Connection Factory Settings 


"\ What /f /s or Does 


TJame 


Identifies this connection factory; not used outside 
Administration Console. 


JNDIName 


The JNDI name for this connection factory. 


Client ID 


This field should be left blank unless you will be supporting 
durable subscribers. Messagesfor a durable subscriber will be 
held, even if the subscriber is not running. 


Default Priority 


Assigns a priority to messages that don't have a specified prior- 
ity. This value should range between 0 and 9. This determines the 
order in which messages will be processed as they are received. 


Default Time 
to Live 


The amount of time, in milliseconds, thatthe message is 
retransmitted. If a message fails to reach its destination, the 
message is retransmitted until the time to live expires. 


Default Time to 
Deliver 


The amount of time, in milliseconds, that must pass before a 
message is delivered. The default value of 0 means instant. 


Default Delivery 
Mode 


The delivery mode, if no delivery mode is specified in the 
message. This value is either Persistent or Non-Persistent. 


Default 

Redelivery Delay 


The time, in milliseconds, before a recovered message is 
redelivered. 


Maximum 
Messages 


The maximum number of simultaneous messages supported. 
The default value is 10. 


Overrun Policy 


Specifies what WebLogic should do if the maximum number of 
messages is reached. This value is KeepOl d or KeepNew. That 
is, is it better to keep older or newer messages? You must decide 
which one will affect the reliability of your applications the most. 


Allow Close In 
OnMessage 


Determines whether WebLogic allows a client to issue a close 
in the OnMessage method. This Boolean value is True or 
Fal se. 


Acknowledge 
Policy 


Allows compatibility with a pervious specification of JMS. 
This value should always be set to Al 1 . 


Load Balancing 
Enabled 


Determines the degree to which load balancing is used in a 
cluster. If true, each message is load balanced. Load balancing 
refers to the process by which WebLogic chooses a server in 
the cluster to handle the request. For more information on clus- 
tering, see Chapter 16. 


Server Affinity 
Enabled 


Determines whether subsequent requests should be handled 
by the same machine when load balancing is enabled. 
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Defining a backing store 



3 you've created a connection factory, you can create a backing store. 
'oi a backing store is optional. The steps to create the backing store 



follow: 



1. On the left side of the Administration Console screen, click the follow- 
ing folders: Services, JMS, and then Stores. 

The screen shown in Figure 15-3 appears. From here, you can see all 
current stores and create connection factories. 

2. Create a JDBC-based or file-based store. 

To create a JDBC-based store, follow these steps: 

a. Click the Configure a new JMS JDBC Store link. 

b. Type a name such as MyJMS JDBC Store. 

c. Select the connection pool to use, as shown in Figure 15-4. 

For more information on connection pools, see Chapter 12. 

d. If necessary, specify a prefix. 

Some databases require a prefix. For example, SQL Server requires 
the dbo prefix for all table names. 

e. Click Create. 

To create a file-based store, follow these steps: 

a. Click the Configure a new JMS File Store link. 

b. Type a name, such as MyJMS File Store. 

c. Select a directory to hold the files, as shown in Figure 15-5. 
You have to scroll down to see the directory. 

d. Leave all other settings as is, and then click Create. 

3. Configure your backing store, as follows: 

a. Give your backing store a name. 

You'll use this name later to refer to the store. 

b. Choose Cache-Flush, the default, because it usually provides the 
best performance. 

The synchronous write policy determines how WebLogic will 
handle concurrent writes to the store. 

c. Choose a directory. 

This directory should be on the local hard drive because that loca- 
tion will provide the fastest access. 
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Connected to : localhost 7001 



/o3Dmydomain%2CType%3DDomai 



You are logged in as : admin 



A persistent JMS store is a physical repository for storing persistent message data and 
durable subscribers. A JMS store can also be used for the paging of messages to disk 
when memory has been exhausted. It can be either a JDBC-accessible database or a 
disk-based file. 

When one or more JMS stores are configured in the current WebLogic Server domain, 
this JMS Stores page displays key information about each of them. To create a JMS 
JDBC store, click the Configure a new JMS JDBC Store... link. To create a JMS file store, 
click the Configure a new JMS File Store... link. 

^ Configure a new JMS JDBC Store... 
[^ Configure a new JMS File Store... 
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mydomain> JMS JDBC Stores> Create a new JMSJDBCStor 



Connected to : localhost : 7001 



LEU 



You are logged in as : admin | Logout 
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This page allows you to define a JDBC-accessible database for storing persistent 
messages and durable subscribers. 



A Name: 



MyJMS JDBC Store 



The name of this JDBC-accessible database store. This name must be 
unique within the WebLogic Server instance or its cluster. 



Connection Pool: (none) 



A valid JDBC connection pool (already defined on the system) for this 
JMS JDBC store. 



Prefix Name: 



< 



The prefix name that is prepended to the JMS table names in this JMS 
JDBC store. When prepended to the JMS table name, a format of 
[schema, [catalog. ] ] prefix results in a valid database table 
name. Use a prefix if your RDBMS requires fully-qualified table names or 
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A file-based 
store. 



lH £j Ps«"h "^Favorites ^Medla 0 0' & \3 (& 



f/localhost: 7001 /console/act^ v g, : , 



H mydDmain 
L3 C3 Servers 
C2 Clusters 
CJ Machines 
S CJ Deployments 
□ \^ Services 
LUjCOM 
S -JJDBC 
S 01 JMS 

L3 Cl Connection Factories 
LJ Templates 
□ Destination Keys 
CJ Stores 

CJ Distributed Destination 
CJ Servers 

CJ Foreign JMS Servers 
13 d Messaging Bridge 
CU XML 

O JTA 

E C3SNMP 
Cj WTC 

CJWLEC (deprecated) 
CU Jolt ^ [<J 



> 



onnected to : localhost 7001 



You are logged in as : admin 



This page allows you to define a disk-based JMS file store for storing persistent 
messages and durable subscribers. A dedicated JMS fife store can also be 
defined to temporarily store non-persistent messages that are paged out from 
memory when message loads reach a specified threshold. 



A Name: 



MyJMS Filestore 



The name of this disk-based file store. This name must be unique within 
the WebLogic Server instance or its cluster. 

Synchioiioiis Wiite Policy: Cache-Flush ^v] 

A policy that determines how this JMS file store writes data to disk. This 
policy also affects the JMS file store's performance, scalability, and 
reliability. Disabled means that transactions complete as soon as file 
store writes are cached in memory, instead of waiting for the writes to 
successfully reach the disk. Cache-Flush means that transactions 
cannot complete until all of their writes have been flushed down to disk. 
Direct-Urite means that all file store writes are written directly to 
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Backing stores are used also for paging stores. If you'll be using a paging store, 
you have to go through the preceding steps twice to create an additional back- 
ing store for your paging store. Paging stores are discussed later in this section. 



jj^r^fe You may be wondering what tables are used by a JDBC-based store. The next 



time you restart WebLogic, several system tables are automatically created to 
hold the message store. 




Defining destination keys 

If you want, you can create destination keys to determine the order in which 
messages are delivered. Destination keys operate on the user-definable proper- 
ties stored in a message. Follow these steps if you want to define a destination 
key: 

1. On the left side of the screen, click the following folders: Services, 
JMS, and then Destination Keys. 

The screen shown in Figure 15-6 appears. From here, you can see all 
current destination keys (if any) and create destination keys. 

2. Click the Configure a new JMS Destination Key link. 



The screen shown in Figure 15-7 appears. 
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Connected to : localhost 7001 



You are logged in as : admin 



A JMS destination key allows you to define the sort order of messages that arrive on a 
specific JMS destination (queue or topic). 

When one or more JMS destination keys are configured in the current WebLogic Server 
domain, this JMS Destination Keys page displays key information about each of them. To 
create a JMS destination key, click the Configure a new JMS Destination Key... link. 

D' OjnfinuK- a JMS Destination h>v 
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mydomain> JMS Destination Keys> Create a n 
JMSDestinationKey... 



Connected to : localhost : 7001 



You are logged in as : admin 
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Notes 



This page allows you to define sorting keys for JMS destinations (queue or topic). 
You can create destination keys to define the sort order for messages that arrive 
on a specific JMS destination. 



& Name: 



MyJMS Destination Key 



The name of this JMS destination key. 



Sort Key: (none) 



The message property name or the name of a message header field on 
which to sort. Message header field keys start with the letters "JMS" and 
ignore the Key Type field. (For better performance, use message header 
fields as sorting keys, rather than message properties.) 



Key Type: | String [v] 



< 



The expected sort key type for this JMS destination key. (This field is 
ignored for message header field keys, which have an implied type.) 
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3. Configure your destination key. 

a. Type a name for the destination key. 

This is for your reference in Administration Console. 

b. Type the name of the Sort Key to filter on. 



c. Using the Key Type field, select the type of data that you expect 
the Sort Key to be. 

d. Choose the direction in which you want sorting to take place. 
4. Click Create. 

You now have a destination key that sorts messages as you've instructed. 



Defining templates 

If you have a number of destination keys that you want to apply to one or 
more JMS servers, queues, or topics, templates can make this process much 
easier. Creating a template is an optional step and makes sense only if you've 
defined quite a few destination keys. 

To create a template, follow these steps: 

1. On the left side of the Administration Console screen, click the follow- 
ing folders: Services, JMS, and then Templates. 

The screen shown in Figure 15-8 appears. From here, you can see all cur- 
rent templates (if any) and create templates. 

2. Click the Configure a new JMS Template link. 

3. Type a name for your template. 

To follow along with the example, type MYJMS Template. 

4. Click Create. 

5. Add keys to your template. 

Select a key, and click the right-facing arrow to move the keys from the 
Available list to the Chosen list. See Figure 15-9. Then click Apply. 

You now have a template that allows you to easily group multiple destination 
keys. 
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onnected to : localhost 7001 



You are logged in as : admin 



A JMS template provides an efficient means of defining multiple destinations (queues and 
topics) with similar configuration settings. This way, you do not need to re-enter every 
configuration setting each time you define a new destination; you can use the JMS 
template and override any configuration setting to which you want to assign a new value. 
Also, you can modify shared configuration settings dynamically simply by modifying the 
template. In addition, a JMS template must be defined and assigned to a JMS server if 
you want to take advantage of the JMS Temporary Destination (queues and topics) 
feature. 

When one or more JMS templates are configured in the current WebLogic Server domain, 
this JMS Templates page displays key information about each of them. To create a JMS 
template, click the Configure a new JMS Template... link. 

[^ Configure a new JMS Template.. . 
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mydomain> JMS Templates> Create a new JMSTemplate.. 



Connected to : localhost : 7001 



You are logged in as : admin 



Note 



Geneial | Thresholds & Quotas | Override | Redelivery | Expiration Policy [_ 

This page allows you to define the general configuration of this JMS template. The 
JMS template attributes are inherited by the JMS destinations that use them, with 
the exception of the Name attribute, which is valid for the JMS template only. You 
must explicitly define a unique name for all JMS destinations created from this 
JMS template. 



4 Name: 



MyJMS Template 



The name of this JMS template. 
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Creating a JMS seri/er 



re ready to create your JMS server, tying together — in one server — 
he components you created previously To create a JMS server, follow 
these steps: 

1. On the left side of the Administration Console screen, click the follow- 
ing folders: Services, JMS, and then Servers. 

The screen shown in Figure 15-10 appears. From here, you can see all 
current servers (if any) and create servers. 

2. Click the Configure a new JMSServer link. 

3. Configure your server as follows: 

a. Select a name for your JMS server, such as My JMS Server (see 
Figure 15-11). 

b. Select a store. 

This is the store that you created previously Using a store is 
optional. 

c. Select a paging store. (This step is optional.) 

A paging store uses the same type of store as a backing store. If 
you choose to use a paging store, you should create two backing 
stores. (See the "Defining a backing store" section for more infor- 
mation.) This paging store holds messages as they come in and are 
waiting to be processed. 

d. Specify a temporary template. (This step is optional.) 

If you specify a value for a temporary template, it will be used to 
create temporary destinations, which are destinations created by 
Java programs, without Administration Console. 



The paging store stores messages that can't fit into memory This allows you 
to handle more simultaneous messages than your current memory allows. 




Because of the heavy use that a paging store receives, always choose to make 
your paging store file based, rather than JDBC based. 

After you've completed these steps, you have a JMS server ready for use. 
You're now ready to create queues or topics for this server. 
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onnected to : localhost 7001 



You are logged in as : admin 



A JMS server manages connections and message requests on behalf of JMS clients. 

When one or more JMS servers are configured in the current WebLogic Server domain, 
this JMS Servers page displays key information about each of (hem. To configure a new 
JMS server, click the Configure a new JMS Server... link. 
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mydomain> JMS Servers> Create a new JMSServer... 



Connected to : localhost : 7001 



You are logged in as : admin | Logout 



| Target and Deploy 
~ GeiieralHr^Tnssholdss! Quotas | 

This page allows you to define the general configuration parameters for this JMS 
server. A JMS server manages connections and message requests on behalf of 
clients. (You must define a JMS server before you can configure any JMS 
destinations.) 



& Name: MyJMS Server 

The name of this JMS server. 



Persistent Store: 



(none) v 



The persistent store (either file-based or JDBC-based) for this JMS 
server, which will be used as a physical repository for storing persistent 
message data. In order to select a store, first configure either a JMS file 
store or JDBC store using the JMS > Stores node. The selected store 
cannot be the same as the selected paging store, or the same store 
used by any other JMS server. 
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Creating queues and topics 



pned, WebLogic supports two styles of message-based communica- 
u use a queue with point-to-point communications or a topic with 
publish-and-subscribe communications. Your client programs communicate 
directly with the JMS queue. In this section, you find out how to create both 
queues and topics. 



Here you tie many of the components that you previously created together 
into one server. To create a JMS queue or a topic, follow these steps: 

1. On the left side of the Administration Console screen, click the follow- 
ing folders: Services, JMS, and Servers. Then click your server name, 
and finally click the Destinations folder. 

2. Click the Configure a new JMSOueue or Configure a new JMS Topic 
link. 

The screen shown in Figure 15-12 appears if you chose to configure a 
queue. 



Figure 15-12: 

Creating a 
queue. 
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mydomain> JMS Servers> MyJMS Server> JMS Queues> Create 
a new JMSQueue... 



wectedto : localhost 7001 



You are logged i 



Monitoring | Notes | 



I General ^TiresiiGlo^^kJ^ Redelivery 

This page allows you to define the general configuration parameters for this JMS 
queue. 



& Name: MyJMS Queue 

The name of this JMS queue. 
& JNDI Name: 



The JNDI name used to look up this queue within the JNDI namespace. 
& 0 Replicate JNDI Name In Clustei 

Specifies whether the JNDI name for this JMS queue (if specified) is 
replicated across the cluster. If this option is not selected, then the JNDI 
name fur the JMS queue (if specified) is only visib e from the server 
hosting this JMS queue. 
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3. Type the configuration information for the queue or topic as follows: 

a. Type a name for the queue or topic. 

Type a JNDI name that clients can use to locate this queue or 
topic. 

c. Click Apply to enable your store. 

d. Choose your template. 

e. Choose the destination keys. 

4. Click Create. 

You've created a JMS message service with either a queue or a topic. Now 
you're ready to begin using this message store from client programs. 



Accessing \lour Message Service 

In this section, you construct a Java application that can access the message 
service that you just created. To begin, review Table 15-2, which lists many of 
the classes used to construct a client program for JMS. 



Table 15-2 


JMS Classes 




JMS Class 


What It Does 




Connecti on 


Represents an open communication channel to the mes- 
saging system. The Connecti on object is used to 
create sessions. 


Connecti on Consumer 


Represents a consumer that retrieves server sessions to 
process messages concurrently. 


Connecti onFactory 


Encapsulates connection configuration information. A 
connection factory is your entry point into the JMS 
server, as the connection factory is used to create con- 
nections. You look up a connection factory using JNDI. 


Desti nati on 


Identifies a queue or topic by its address. 




Message 


Holds the message being sent. 




MessageProducer 
and MessageConsumer 


Specifies the interface for sending and receiving 
messages. The MessageProducer class sends mes- 
sages to a queue ortopic;the MessageConsumer 
class receives messages from a queue or topic. 
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Table 15-2 (continued) 


•\ [j/ri%6lass 


What It Does 


ServerSessi onl 


Associates a thread with a JMS session. 


ServerSessi on 
Pool 1 


Holds a pool of server sessions that can be used to 
process messages concurrently for connection 
consumers. 


ServerSessi onPool 
Factory 


Encapsulates configuration information for a server- 
managed pool of message consumers. Used to create 
server session pools. 


Sessi on 


Specifies a serial order for the messages produced 
and consumed. 



The following sections describe these classes in greater detail. After that, 
you create a simple example that accesses a queue and a topic. 



Connection Factory 

The Connecti on Factory class is your entry into the JMS server. After you 
obtain Connecti onFactory, you can establish connections to the queues 
and topics of a JMS server. The Connecti onFactory class supports concur- 
rent access, so you can use one Connect ion Fa ctory object for multiple 
threads. 

Connection factories are created by the systems administrator. All 
Connecti on Factory objects are identified using WebLogic JNDI names. 
A client program looks up Connecti onFactory using its unique JNDI name. 

By default, WebLogic JMS provides one connection factory It can be accessed 
by using the JNDI name weblogic.jms. Connect ion Fa ctory. You need to 
define a connection factory only if the default provided by WebLogic JMS is 
not suitable for your application. 



Connection 

You use the Connecti onFactory object to obtain a Connecti on object, which 
is an open communications channel between an application and the messag- 
ing system. From this Connecti on object, you create Sessi on objects for pro- 
ducing and consuming messages. A connection creates both server-side and 
client-side objects that manage the messaging between the application and 
JMS. Like Connecti onFactory, Connecti on objects support concurrent use, 
enabling multiple threads to access the object simultaneously. 
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Connections require considerable resources. Because of this, most applica- 
tions use one connection for all JMS processing. 

OKS 

Session 

Session objects are obtained from Connection objects by calling the 
createQueueSessi on or createTopi cSessi on method. A Sessi on object 
defines the order that messages are produced and consumed. A Sess i on 
object can create multiple message producers and message consumers. 

Session objects should not be shared across threads. It's okay for the same 
thread to both produce and consume messages. However, if an application 
wants a separate thread for producing and consuming messages, the applica- 
tion should also create separate sessions for producing and consuming 
threads. Creating threads is illegal in EJBs. 



Destination 




ADesti nation object represents either a queue or topic. Destinations refer 
to destination keys, which you set up earlier using Administration Console. 
The Desti nati on object allows the application program to communicate 
with the topic or queue. 

A Desti nati on object supports concurrent use. This allows multiple threads 
to access the object simultaneously. 



Message Producer and MessageConsumer 

You use the Sessi on object to create the MessageProducer and Message 
Consumer objects, which are attached to queues and topics. A Message 
Producer object sends messages to a queue or topic. A MessageConsumer 
object receives messages from a queue or topic. 

The MessageProducer and MessageConsumer objects operate independently 
The MessageProducer object sends messages regardless of whether a 
MessageConsumer object has been created and is waiting for a message and 
vice versa. 



Message 

The Message class holds the information to be exchanged by applications. 
Following are the three main components to a Message object: 
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Standard header fields 
Application-defined properties 



message body 

The following sections examine the header fields and the message body . 
Message header fields 

JMS messages contain a standard set of header fields by default. Some of 
these fields can be modified by the sender. Table 15-3 describes the fields in a 
JMS message. 



Table 15-3 



Message Header Fields 



Field 


Defined By 


What It Does 




JMSCorrel ati on 


Application 


Relates messages to each other. This field 


ID 




is often used to relate a reply message to the 






original request message. 




JMSDel i very 


send( ) 


Specifies a PERSISTENT messag 


e, 


Mode 


method 


which is stored by JMS and is not 


consid- 



ered successful until sent, or a NON - 
PERSISTENT message, which is simply 
transmitted and requires much less overhead. 



send( ) Specifies the time at which the message 

method was sent. This field is used to sort messages. 

send( ) Stores the destination queue or topic to 

method which this message is targeted. 



JMSDel i veryTime 



JMSDesti nati on 



JMSExpi rati on 



send( ) Specifies the expiration time for the mes 
method sage. After the expiration time is reached, 
the message is no longer delivered. 



JMSMessagelD 



send( ) 
method 



Uniquely identifies this message. 



JMSPriority Message Specifies the priority for this message. 

Consumer Priority levels range from 0 to 9, with 0 the 
lowest priority. 



JMSRedel i vered 



WebLogic Specifies whether this message was redeliv 
JMS ered due to non-receipt. 



JMSReplyTo Application Specifies what message this message is a 

reply to, if it is a reply. 
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Defined By 


What It Does 
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Message 


Contains the time at which the message was 




Consumer 


sent. 


JMSType 


Application 


Specifies an application-defined type. 



Message body 

The body of a message contains the content that's being delivered. JMS sup- 
ports a variety of content types, as shown in Table 15-4. 



Table 15-4 


JMS Message Types 




Type 


What It Is 








javax. jms . 
BytesMessage 


A stream of bytes. There is no implied meaning, 
form is accessed using stream-oriented readers 
ers based onjava.io.DatalnputStreama 
i o . DataOutputStream. 


Data in this 
and writ- 
nd j a va . 


javax. jms . 
MapMessage 


A set of name/value pairs in which the names are strings 
and the values are Java primitive types. 


javax. jms . 

ObjectMessage 


A single ser 


ializable Java object. 




javax. jms . 
StreamMessage 


A stream where only Java primitive types are written to or 
read from the stream. 


javax. jms . 


A string message. 





TextMessage 

webl ogi c . jms . XML content. Although XML can be stored in 

extensi ons . TextMessage, XMLMessage allows message filtering. 

XMLMessage 



Creating a PoinUto-Point JMS Client 

In this section, you create a simple point-to-point (P2P) JMS client that sends 
text messages from one client to another. You can build on this simple example 
to create a more complex messaging system. 
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Creating the receiver 



iver program, shown in Listing 15-1, waits for messages. The receiver 
ar Java application that you can run from the command line. Unlike 
an EJB, the receiver doesn't have to run in the context of WebLogic. In this 
example, both the sender and receiver are standalone Java applications that 
run outside WebLogic. WebLogic is only providing the infrastructure to pass 
the messages. 



Listing 15-1: P2P Receiver 

import j avax. jms.*; 
import j avax . nami ng . * ; 
import Java . uti 1 .*; 



public class Sampl eQueueRecei ver implements MessageLi stener { 

private boolean done = false; 

private Context ctx = null; 

private QueueConnecti onFactory connecti onFactory = null; 

private QueueConnecti on connection = null; 

private QueueSession session = null; 

private QueueRecei ver receiver = null; 

private Queue queue = null; 

private Hashtable ht = null; 



public void init() { 
try { 



ht = new Hashtabl e ( ) ; 



ht .put (Context . INITIAL_CONTEXT_FACTORY , 

"webl ogi c . j ndi . WLIni ti al Con text Factory" ) ; 
ht.put(Context.PROVIDER_URL, " t3 : //I ocal host : 7001 " ) ; 

ctx = new InitialContext(ht) ; 

connecti on Factory =( QueueConnecti on Factory) 

ctx. lookup( " we blogic. jms. Connecti onFactory"); 
connection = connecti on Factory . createQueueConnecti on () ; 
session = connecti on . createQueueSessi on ( 

f al se , 

j avax. jms. QueueSession. AUT0_ACKN0WLEDGE ) ; 
queue = (Queue) ctx. 1 ookup( "MyJMSQueue" ) ; 
receiver = sessi on . createRecei ver(queue ) ; 



receiver.setMessageListener(this); 

connection .start( ) ; 
catch ( Exception e ) I 
Sy stem. out. println(e); 
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ic void closeO throws JMSException I 



try ( 

recei ver . cl ose ( ) ; 
session . cl ose( ) ; 
connecti on . cl ose( ) ; 
) catch ( Exception e ) { 
System.out.println(e); 

) 

) 

public void onMessage(Message message) { 

if ( message instanceof TextMessage ) I 
try ( 

TextMessage textMessage = (TextMessage) message; 
String msg = textMessage . getText( ) ; 

System . out . pri ntl n (" Recei ved message: " + msg); 

if ( msg .equal s( "exi t" ) ) { 
synchronized (this) { 
done = true; 
this .notifyAl 1 ( ) ; 



) catch ( Exception e ) { 
System.out.println(e) ; 



) 

public static void mai n ( Stri ng[ ] args) I 

try { 

Sampl eQueueRecei ver sqr = new Sampl eQueueRecei ver( ) 
sqr . i ni t ( ) ; 

System . out . pri ntl n ( "Wai ti ng for messages...."); 

synchronized (sqr) { 
while ( Isqr.done ) { 
try { 

sqr . wai t ( ) ; 
) catch ( InterruptedExcepti on ie ) { 



(continued) 
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sqr . cl ose( ) ; 
atch ( Exception e ) 
ystem.out.println(e) 



The program begins execution at the ma i n method, which instantiates an 
object of the sample receiver and begins waiting for messages. The class 
implements the MessageListener interface. This allows the class to receive 
messages. Implementing this interface requires that the onMessage method 
be provided by your class. 

Next, the i n i t method is called. The i n i t method contains the code that 
registers this object to receive messages from the MyJMSQueue queue. The 
connection is retrieved from the connection factory and is started by calling 
the start method of the connection object. 

When a message is received, the onMessage method is called. All message pro- 
cessing takes place inside this message. This program deals with only Text 
Message type messages. The program begins by examining the object sent to 
onMessage to determine whether it was TextMessage. If it was TextMessage, 
the message is displayed. If the message was not TextMessage, the message is 
ignored. After you execute the receiver, it begins waiting for messages. 



Creating the sender 

In this section, you create a sender that works with the receiver you created 
in the preceding section. The sender is shown in Listing 15-2. 



Listing 15-2: P2P Sender 

import javax.jms.*; 
import j avax . nami ng . * ; 
import Java . uti 1 .*; 

public class Sampl eQueueSender { 

public static void mai n ( Stri ng[ ] args) { 

Context ctx = null; 

Hashtable ht = new HashtableO; 

QueueConnecti onFactory connecti on Factory = null; 

QueueConnecti on connection = null; 

QueueSession session = null; 

QueueSender sender = null; 

Queue queue = null; 
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TextMessage message = null; 



Hit .put (Context . INITIAL_CONTEXT_FACTORY , 

"webl ogi c . j ndi . WLIni ti a 1 Context Factory " ) ; 
ht.put(Context.PR0VIDER_URL, "t3 : //l oca 1 host : 7001 ") ; 

ctx = new Ini ti al Context ( ht ) ; 
connecti on Factory = 
(QueueConnectionFactory) 

ctx. lookupC we blogic.jms. Connect ionFactory"); 
connection = connecti on Factory . createQueueConnecti on () ; 
session = connecti on . createQueueSessi on ( fal se , 

javax.jms.QueueSession .AUT0_AC KNOW LEDGE ) ; 
queue = (Queue) ctx. 1 ookup( "MyJMSQueue" ) ; 
sender = sessi on . createSender(queue ) ; 

Sy stem. out. printlnC Send ing messages. . ."); 

message = sessi on . createTextMessage () ; 

for ( int i = 1; i <= 10; i++ ) { 
String str = "Message " + i; 

message. cl earBody( ) ; 
message . setText ( str ) ; 

System . out . pri ntl n ( "Sendi ng message: " + str); 
sender. send(message); 



message . cl earBody ( ) ; 
message . setText ( "exit") ; 
me ssage.setIntProperty( "severity", 0); 
System . out . pri ntl n ( "Sendi ng message: exit"); 
sender, send (message); 
) catch ( Exception e ) I 

e . pri ntStackTrace( ) ; 
) finally { 
try { 

sender . cl ose ( ) ; 

sessi on . cl ose( ) ; 

connecti on . cl ose ( ) ; 
) catch ( Exception e ) { 

e.printStackTraceO; 




} 



The sender is somewhat simpler than the receiver, containing only one 
method, the main method. The sender simply opens a connection, sends 
some messages, and exits. 
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After the queue is located using JNDI and the connection is opened, the client 
program transmits ten messages. First a message is created: 

= sessi on . createTextMessage( ) ; 

This message is reused multiple times to send each message. The program 
loops through and sends the text message ten times: 

for ( int i =1; i <= 10; i++ ) { 
String str = "Message " + i; 

The message is cleared, and then the text is defined. Then the message is 
sent using the send method of the sender: 

message . cl ear Body ( ) ; 
message.setText(str) ; 

System . out . pri ntl n ( "Sendi ng message: " + str); 
sender. send (message); 

) 

The sender and receiver transmit ten messages, as shown in Figure 15-13. 
The P2P sender and receiver model works well when you want to send mes- 
sages between two programs. You can also send a message from one sender 
to many receivers. You find out how to do this in the next section. 



DropBocfe 



C:\WebLogicExamples\chl5 >runQueueReceive 

Waiting for messages.... 

Received message: Message 1 

Received message: Message 2 

Received message: Message 3 

Received message: Message 4 

Received message: Message 5 

Received message: Message ft 

Received message: Message 7 

Received message: Message 8 

Received message: Message 9 

Rece ived message : Message 10 

Received message: exit 



Figure 15-13: 

AP2P 
message. 
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Creating a Publish-and-Subscribe 



In this section, you use the publish-and-subscribe model. In this model, you 
have many subscribers and one publisher. (This is similar to a newspaper.) 
The same message is sent from the publisher to all the subscribers. You 
begin by constructing the subscriber. 



The subscriber for a publish-and-subscribe model is similar to the receiver 
discussed in the preceding section. The subscriber receives messages using a 
MessageLi stener interface. See Listing 15-3. 

Listing 15-3: Subscriber 

import j avax . jms .* ; 
import j avax . nami ng . * ; 
import Java . uti 1 .*; 



public class Sampl eTopi cSubscri ber implements MessageLi stener 
{ 

private boolean done = false; 
private Context ctx = null; 
private Hashtable ht = null; 

private Topi cConnecti onFactory connecti onFactory = null; 
private Topi cConnecti on connection = null; 
private TopicSession session = null; 
private Topi cSubscri ber subscriber = null; 
private Topic topic = null; 

public void init() { 



ht = new Hashtable ( ) ; 

ht .put (Context . INITIAL_CONTEXT_FACTORY , 

"webl ogic.jndi .WLIniti a 1 Context Factory" ) ; 
ht.put(Context.PROVIDER_URL, "t3 : //l oca 1 host : 7001 ") ; 

ctx = new InitialContext(ht) ; 

connecti on Factory = (Topi cConnecti onFactory ) 




Creating the subscriber 



try 



ctx. lookup( " we blogic. jms. Connecti onFactory"); 

(continued) 
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connection = connecti on Factory . createTopi cConnecti on ( ) 
session = connecti on . createTopi cSessi on ( fal se , 

javax.jms.QueueSession .AUT0_AC KNOW LEDGE ) ; 
topic = (Topic) ctx . 1 ookup( "MyJMSTopi c" ) ; 
subscriber = sessi on . createSubscri ber ( topi c ) ; 
subscriber.setMessageListener(this); 



connection .start( ) ; 
) catch ( Exception e ) { 
Sy stem. out. println(e); 

) 

} 



public void closeO throws JMSException { 



try I 

subscri ber . cl ose( ) ; 
sessi on . cl ose( ) ; 
connecti on . cl ose( ) ; 
) catch ( Exception e ) { 
e.printStackTraceO; 

) 

} 



public void onMessage(Message message) { 

if ( message instanceof TextMessage ) { 
try I 

TextMessage textMessage = (TextMessage) message; 

String msg = textMessage . getText( ) ; 

System . out . pri ntl n (" Recei ved message: " + msg); 

if ( msg . equal s ( "exi t" ) ) { 
synchronized (this) { 
done = true; 



thi s . noti fyAl 1 ( ) 



catch ( Exception e ) 
e.printStackTraceO; 



public static void mai n ( Stri ng[ ] args) { 
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try ( 

Sampl eTopi cSubscri ber ts = new Sampl eTopi cSubscri ber ( ) ; 



its . ini t( ) ; 

System . out . pri ntl n ( "Wai ti ng for messages...."); 



synchronized (ts) { 
while ( Its. done ) { 
try { 

ts.waitC ) ; 
) catch ( InterruptedExcepti on ie ) ( 
) 

) 

) 



ts . cl ose( ) ; 
) catch ( Exception e ) I 
e . pri ntStackTrace( ) ; 

} 

) 

} 



The program is nearly the same as the receiver in Listing 15-1. The main dif- 
ference is that the other program connects to a queue, and this program con- 
nects to a topic. By connecting to a topic, you establish a nonexclusive 
relationship to the publisher. After the connection is established, you receive 
messages in the same way as any other subscribers. 



Creating the publisher 

The publisher for a publish-and-subscribe model is similar to the sender in 
the preceding section. The publisher sends messages, except these messages 
can be sent to many subscribers. Listing 15-4 shows a publisher. 



Listing 15-4: Publisher 

import javax.jms.*; 
import j avax . nami ng . * ; 
import Java . uti 1 .*; 

public class Sampl eTopi cPubl i sher { 

public static void mai n ( Stri ng[ ] args) ( 

Context ctx = null; 

Hashtable ht = new HashtableO; 

Topi cConnecti onFactory connecti on Factory = null; 

(continued) 
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Topi cConnecti on connection = null; 
picSession session = null; 
'pi cPubl i sher publisher = null; 
Topi c topi c = null; 
TextMessage message = null; 



try ( 

ht .put (Context . INITIAL_CONTEXT_FACTORY , 

"webl ogi c . j ndi . WLIni ti al Context Factory " ) ; 
ht.puUContext.PROVIDERJJRL, " t3 : //I ocal host : 7001 " ) ; 

ctx = new InitialContext(ht) ; 

connecti on Factory = (Topi cConnecti onFactory ) 

ctx. lookupC we blogic.jms. Connect ionFactory"); 
connection = connecti on Factory . createTopi cConnecti on () ; 
session = connecti on . createTopi cSessi on ( 

f al se , 

javax.jms.TopicSession .AUT0_AC KNOW LEDGE ) ; 

topic = (Topic) ctx . 1 ookup( "MyJMSTopi c" ) ; 
publisher = sessi on . createPubl i sher ( topi c ) ; 

System . out . pri ntl n (" Publ i shi ng messages . . . " ) ; 

message = sessi on . createTextMessage () ; 

for ( int i = 1; i <= 10; i++ ) { 
String str = "Message " + i; 

message. cl ear Body () ; 
message . setText ( str ) ; 

System . out . pri ntl n (" Publ i shi ng message: " + str); 
publ i sher. publ ish( message); 

) 



) catch ( Exception e ) { 

System.out.println(e); 
) finally ( 
try { 

publ i sher . cl ose( ) ; 
sessi on . cl ose( ) ; 
connecti on . cl ose ( ) ; 
) catch ( Exception e ) { 
System.out.println(e) ; 
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The program is nearly the same as the sender in Listing 15-2. The main differ- 
ence is that the other program connects to a queue whereas this program 
ot£ to a topic. By connecting to a topic as a publisher, you can send 
^^sages to many clients. You receive messages the same way as any 
- subscribers does. 

The sender and receiver transmit ten messages, as shown in Figure 15-14. 
As you can see from the figure, one publisher is sending messages to two 
subscribers. 
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As you've found in this chapter, you can easily use WebLogic as the infra- 
structure to send messages between programs. You can do this using either a 
point-to-point or a publish-and-subscribe model. 
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In this part . . . 



#^ere is where you find out about more advanced con- 
¥ W figuration options. For example, WebLogic allows 
you to combine individual servers into one large virtual 
server. This feature, called clustering, enables you to 
expand your system by adding hardware rather than by 
completely replacing your existing system. 

Security is very important to any web application. In this 
part, you find out about the WebLogic features that allow 
you to secure data exchanged with your system and con- 
trol how users access your system. You also find out how 
to tune your system for maximum performance. 



Chapter 16 

Worfing with Server Clusters 



In This Chapter 

Understanding the benefits of clustering 
Naming the components of WebLogic clustering 
Configuring clustering 
Using JDBC resources with clustering 



7 he old saying that there's strength in numbers applies to computers as 
well as to humans. You can achieve considerable advantages by using 
many computers together to run WebLogic. These groups of computers are 
called clusters. These clusters can appear as a single server, which delegates 
tasks to the appropriate computer in the cluster. 

In this chapter, you discover the advantages and disadvantages of using clus- 
tering. You uncover the components that make up a cluster, and then you set 
up a cluster. 



Understanding Clustering 

A cluster is a group of computers that collectively perform the same task. 
In the case of a WebLogic cluster, the tasks performed by the cluster include 
all the tasks that you might assign to one WebLogic Server. These tasks are 
covered throughout this book. 

The two main reasons why you might want to create a WebLogic cluster are 
performance and reliability The disadvantages to setting up a cluster have to 
do with the costs of hardware, software, and administration: 



Hardware cost. A cluster contains at least twice the amount of computer 
hardware that you would have with a single computer system. You also 
have additional repair costs to keep these computers up and running. 
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V Software cost. You need a cluster license for WebLogic. This increases 
the amount of money that it costs to purchase your server software. In 



jtion to WebLogic, other third-party software that you're using may 
ire additional license fees when used with a cluster. 



Administration cost. Every network administrator knows that more 
computers means more support time. It takes time to install the required 
software to the additional computer systems in your cluster. 




Even if your system easily fits on one machine, you should still be aware of 
how clustering works. There may come a point when your application has 
grown large enough that clustering will be needed. If you know how clustering 
works, you can construct your application so that it can support clustering 
when it's needed. 



Performance through clustering 

Clustering can increase performance because you have additional computers 
to handle requests, rather than just one computer. However, clustering doesn't 
necessarily result in an increase in speed. The amount of performance gain 
from clustering is determined by the type of application you're running. 

When clustering can't improve performance 

Consider a system that calculates economic forecasts when given current 
market conditions. This program must access a large amount of historical 
data to produce its output. This program is hosted on WebLogic Server. Only 
a few users will access this program throughout the day. The response time 
is slow, in that the program takes a while to generate the forecast. 

A cluster would not likely increase the speed of this application. Clusters 
improve performance primarily when they serve a large number of concurrent 
requests. In this example, a lengthy process is executed by just a few users. If 
an additional computer were added to the system to form a cluster, the second 
computer would sit idle while the first performed the forecast. A server cluster 
is not capable of splitting a single request among the cluster members. The 
only case where the cluster would speed up this process is if several users 
where submitting requests at the same time. 

To speed up the forecast application, you'd need to buy a larger, faster server 
or rewrite the application to be more efficient. 

When clustering can improve performance 

Now consider a system that allows users to look up information about any of 
the products that their company produces. This program allows the user to 
view sales reports on each item. This system is accessed by users throughout 
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the company. Additionally, many automated programs access the system 
through EJB calls to obtain sales information. 



m has been giving unacceptably bad response times, especially 
during peak usage. Additionally, the server sometimes goes off-line from 
excessive use. 

A cluster would improve the performance of this application. By having more 
than one server available to process the requests, no individual server would 
be overworked. This would result in faster responses, and the system wouldn't 
go off-line due to one overloaded server. 

Perhaps the most important thing to keep in mind when deciding whether to 
use a cluster to improve performance is that a cluster will only allow the 
system to handle more requests faster. It will not often speed up requests 
when these requests come in one at a time. A cluster is used to increase the 
performance for many concurrent accesses. 



Reliability through clustering 

Performance is not the only reason to consider clustering. Reliability is 
another factor. A cluster can increase reliability because several computer 
systems handle the requests sent to the server. If one computer in the cluster 
crashes, the cluster remains operational. 

Reliability, unlike performance, is always improved by clustering. Therefore, 
whether or not to run a cluster to increase reliability boils down to a question 
of cost. 



Components of WebLoqic Clustering 

Unfortunately, clustering is not something that you can set up by changing a 
simple configuration setting. Many related systems are used to set up a cluster: 

u* Node Manager 
u* Clustered domain 
u* Clustered JDBC 
u* Load balancing 
Connection proxy 

In this section, I explain each of these systems and how they fit together to 
allow you to create a cluster of WebLogic servers. 
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Node Manager 




nager is a standalone Java application that allows you to manage the 
efve^fhat make up your cluster. There are two immediate benefits to this. 
You can 



V Manage the cluster from one computer 

Automatically restart crashed cluster computers 

When you create a cluster, it will be made up of several computers. This can 
be somewhat difficult to manage because you will need to start and stop 
server instances on each machine. Additionally, you now have log files on 
each machine. Node Manager allows you to work with the computers in the 
cluster as though they were a single unit. You can quickly restart individual 
cluster computers or obtain information about any machine in the cluster. 

You may choose to use Node Manager after your system is up and running. 
Node Manager is more beneficial when your system has settled into a routine. 
When you're first setting up your system, it's better to directly control the 
computers that make up the cluster. 



Clustered domain 

In other chapters, you work with WebLogic domains. In this chapter, you're 
introduced to the concept of a clustered domain. The clustered domain com- 
bines the computers of the domain into one virtual computer. This makes the 
fact that you're using a cluster nearly invisible to a client program accessing 
your server. To the client program, your cluster looks like one very fast 
single-server system. 

Clustered domains are configured in much the same way as non-clustered 
domains. You can set up both using WebLogic Domain Wizard. 



Clustered JDBC 

Clustered JDBC allows you to use JDBC resources across the cluster. 
WebLogic manages the concurrent access to the connection pools on each 
managed server. Clustered JDBC is set up just like regular JDBC, except the 
JDBC resources are assigned to a cluster rather than to individual servers. 
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Load balancing 

jancing allows WebLogic to send requests to servers that aren't 
as hard as other servers. This prevents one overworked server from 
becoming a bottleneck. As RMI and EJB requests come in, the load-balancing 
algorithm determines which managed server will handle the request. 

WebLogic provides several algorithms for load balancing. You use Adminis- 
tration Console to choose the one you want. These methods are discussed 
later in this chapter. 



Connection proxy 

Clustering is not just for RMI and EJB requests. You may also choose to cluster 
your JSP and servlet requests. WebLogic provides for a connection proxy that 
routes servlet and JSP requests to a managed server that's not overloaded. 

The connection proxy feature of WebLogic is extendable. You may choose to 
write your own, buy a third-party proxy, or use the connection proxy built 
into WebLogic. 



Configuring WebLogic Clustering 

Now that you understand the components that make up a WebLogic cluster, 
it's time to see the steps required to install one. These steps are summarized 
as follows: 

1. Install WebLogic Server. 

2. Create a clustered domain. 

3. Start the WebLogic Server cluster. 

4. Configure Node Manager (optional). 

5. Configure load balancing. 

6. Configure proxy plug-ins (optional). 

7. Configure clustered JDBC. 

In the following sections, you examine each step in detail. 
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Installing WebLogic Server 




install WebLogic Server on each machine that you want to run it on. 
use the same version of WebLogic on each machine and pay for the 
necessary WebLogic licenses. 

Although not required, try to make the environment of each cluster machine 
as close to identical as possible. The directory structure and location of 
WebLogic and your application should be the same on each system. 

The machines that make up the cluster don't need to be identical, but they 
must meet the following minimum requirements: 



V Static IP address. A managed server must have permanently assigned, 
static IP addresses. Dynamically assigned IP addresses are not allowed 
in a cluster environment. 

f Client accessible. The server computers must be accessible to clients. 
You may not place server computers behind a firewall and clients in 
front of the firewall. This is because each server instance must have a 
public IP address that can be reached by the clients. 

Multicast accessible. The managed servers must be located on the same 
local area network (LAN) and must be reachable by IP multicast. This 
means that the IP address configured for each server machine must 
have the same submit mask. 
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You shouldn't use a shared file system to run multiple WebLogic Server 
instances on separate machines. This creates a bottleneck because all server 
instances must compete to access this area. Additionally, concurrent access 
to the log files may cause some logging information to become unreliable. 
Always install a separate copy of WebLogic for each server, preferably on the 
server's local hard drive. 



Creating a clustered domain 

After your software is installed, you're ready to create a clustered domain. In 
other chapters, you create a domain for a single-computer WebLogic installa- 
tion. Here, you create a domain that works with a clustered environment. 

A number of steps are involved in setting up a clustered domain. Here's an 
overview: 

A. Configure your Administration Server. Each domain must have one 
server that you configure as your Administration Server. (See Step 4 in 
the next numbered list.) 
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Configure your managed servers (optional). You can add managed 
servers or change existing ones. (See Step 6 in the next list.) 

gn servers to clusters (optional). You can group your managed 
ers into clusters or change existing groupings of servers. (See 
Step 10.) If you choose this option, you must first configure your cluster. 
(See Step 8.) 

D. Associate servers to machines (optional). You can assign your servers 
and clusters to machines or change existing assignments. (See Step 14.) 
If you choose this option, you must first configure the machine. (See 
Step 12.) 

You begin creating a clustered domain in Domain Configuration Wizard, as 
follows: 

1. Start Configuration Wizard. 

Choose StartOProgramsOBEA WebLogic PlatformODomain 
Configuration Wizard. 

2. Select the Create a new WebLogic configuration link, and then click 
Next. 

The screen shown in Figure 16-1 appears. 



i] BEA WebLogic Configuration Wiz.inl 



Figure 16-1: 

Choose a 
domain 
type. 



Select a Configuration Template 

Select the template below which best corresponds to the type of configuration you need. Configuration templates 
define which components run in the domain, and may also define other applications, data, and services. 



O Domain Configuration Templates 
B C-JBEA 

WebLogic Server Exampies Domain 
Avitek Medical Records Sample Domain 
LjI Platform 

Basic WebLogic Server Domain 

- Basin WebLogic 'workshop Domain 



Description 

Create a basic 'n'n'ebLogic Ser n 



without installing sample applications. 



Author 

BEA Systems, Inc. 



Template Locations 

i Browse C:\bea\weblogic81\common\templates\dornains 
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3. Choose a type of domain, and then click Next. 

To follow along with the example, click Basic WebLogic Server Domain. 

se Customized Configuration, and then click Next. 
The screen shown in Figure 16-2 appears. 

5. Configure your Administration Server as follows: 

a. For the Name box, type a unique name for your server. 

b. Leave the ListenAddress box blank, unless your computer has 
multiple IP addresses. 

c. Leave the ListenPort at 7001 and the SSL Listen Port at 7002. 

d. If you will be using SSL, click the SSL Enabled box. 

For more information about SSL, see Chapter 17. 

e. Click Next. 

The screen shown in Figure 16-3 appears. 

6. Click Yes to begin configuring your managed server, and then click 
Next. 

The screen shown in Figure 16-4 appears. 



Figure 16-2: 

Configure 
your server. 
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Administration Server Configuration 

Each WebLogi.: Server domain must have one server 'hat a:ta aa the ".drfuntatt ation Server 

The Administration Server is where the Administration Console is run and used to perform administrative tasks. 
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Multiple Servers, Clusters, and Machines Options 

Managed Servers, Clusters, and Machines in this WebLogic configu ratio 



Do you want to modifv how your WebLogic configuration is distributed across servers, 
clusters, and physical machines? 

So far, you have only configured the administration server, You may optionally modify how your configuration is 
distributed across managed servers, dusters, and machines by: 

* Adding or changing managed servers. 

* Grouping managed servers into clusters, or changing the current grouping. 

* Mapping these servers and clusters to machines, or changing the current mapping. 

Depending upon the configuration defined in the template and the modifications you make, there are between three 
and five screens in this section. If you choose to skip this section the created configuration will use the settings 
exactly as specified in the template. 

If you select "Yes" and dick "Next", the wizard will lead you through these configuration options. 
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Managed Server(s) Configuration 

A typical production environment may have one or more Managed Servers. 

Each Managed Server is an instance of WebLogic Server used to host enter prise applications. 
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7. For each managed server that you want to add, do the following: 
a. Click Add. 

Under Name, type a unique name for your server. 

c. Under Listen Address, use the IP address of the server that's 
being added. 

This should be the unique IP address that you assigned to the 
server when you installed the operating system and networking 
support on the server. 

d. Under Listen Port, use the port that the computer listens over. 

The range of allowable values is 1 to 65,535. You should accept the 
default value. 

e. Under SSL Listen Port, use the port that the computer listens over. 

The range of allowable values is 1 to 65,535. You should accept the 
default value. 

8. When you have finished adding servers, click Next. 

The screen shown in Figure 16-5 appears. 



Figure 16-5: 

Configure 
the cluster. 



#] BEA WebLorjic Configuration Wiz.ml 
Cluster Configuration 

In a duster deployment multiple WebLogic Server instances (servers) run simultaneously and work together to 
provide increased scalability and reliability. To clients a cluster appears to be a single WebLogic Server instance. 
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9. Configure your cluster as follows: 
Click Add. 

Under Name, type a unique name for your cluster. 

MulticastAddress should specify the IP addresses of your man- 
aged machines. 

MulticastAddress contains a range of IP addresses that the man- 
aged machines are located on. A multicast address is a special IP 
address that broadcasts to all IP addresses on its network. Your 
network administrator will be able to give you the cluster address 
and multicast addresses for your server. 

d. Leave MulticastPort at its default value of 7777. 

The cluster address contains the address and ports for each 
server instance. 

10. When you have finished configuring your cluster, click Next. 

The screen shown in Figure 16-6 appears. 



Figure 16-6: 

Assign 
servers to 
clusters. 
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Servers To Cluster Assignments 

Specify the server! associated with each cluster. 



Select a target in the list box on the right, Then select a source or sources to assign to this target by selecting from the list box on the left., clicking arrows 
to add and delete sources from the target. 
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11. For each server that you want to assign to a cluster, do the following: 
a. On the left, click the server that you want to assign. 



On the right, click the cluster that you want to assign the 
server to. 



c. Click the right arrow to make the assignment. 

12. When you've finished assigning servers to clusters, click Next. 
The screen shown in Figure 16-7 appears. 

13. For each machine that you want to configure, do the following: 

a. Click Add. 

b. Under name, type a unique name for your machine. 

c. Under ListenAddress, type the IP address of the machine you 
are adding. 

d. Under ListenPort, accept the default. 

14. When you've finished configuring machines, click Next. 

The screen shown in Figure 16-8 appears. 



Figure 16-7: 

Configure 
machines. 
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Machine Configuration 

A machine is the logical representation of the computer that hosts one or more WebLogic Server instances (servers) . 
The Administration Server and Node Manager application use the machine definition to start remote servers. 
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15. For each server that you want to assign to a machine, do the following: 

a. On the left side of the screen, click the server you want to assign. 

b. On the right side, click the machine you wish to assign the 
server to. 

c. Click the right arrow to make the assignment. 

16. When you have finished assigning servers to machines, click Next. 

Now that you've set up your distributed domain, you're ready to start your 
cluster. This is discussed in the next section. 



Starting the WebLogic Server cluster 

To start a cluster, you first start Administration Server for the cluster, and 
then start each of the managed servers in the cluster. Each server instance is 
started with a command that you execute in a separate command shell. (For 
a comprehensive discussion of procedures for starting and stopping server 
instances, see Chapter 3.) 

Follow these steps: 
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1. Open a command shell. 

to the domain directory. 

ge the directory to the domain directory that you created with 
Configuration Wizard by issuing the following command: 

cd \bea\user_projects\myc7 uster 

where myc 1 uster is the name of your cluster. 

3. Start Administration Server by typing StartWebLogic at the command 
prompt. 

4. Type the user name and password. 

5. Observe the Administration Server startup. 

The command shell displays messages that report the status of the 
startup process. 

6. Start a managed server as follows: 

a. Open a command shell. 

b. Change the directory to the domain directory that you created 
with Configuration Wizard. 

c. Type the following command: 

StartManagedWebLogic server_name address:port 

Replace server_name with the name of your managed server, and 
replace address -.port with the address and port of 
Administration Server. 

d. To start another server instance in the cluster, return to Step 6c. 

If you have no additional managed servers to start, your startup is 
now complete. 

You may run one managed server on the same computer as Administration 
Server. Because Administration Server doesn't require much processing 
power, this allows you to take full advantage of the computer. 



Configuring Node Manager 

As you saw in the preceding section, the process of starting your cluster 
involves starting up managed servers on all machines in the cluster. This can 
be tedious and time consuming. Node Manager alleviates this tedium. 

Node Manager, which is covered in Chapter 3, is a standalone Java program 
that you can use to start managed servers on remote machines. Node Manager 
can also restart managed servers that may have crashed. You're not required 
to use Node Manager to set up a cluster. 
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Configuring load balancing 



ncing allows WebLogic to better allocate the machines in the server 
his prevents machines from becoming overloaded with tasks. One of 
the biggest tasks for these machines is servicing requests to EJB and RMI 
objects. In this section, you find out how to load balance the machine to 
handle EJB and RMI requests. 

WebLogic uses the following three methods to load balance EJB and RMI 
requests: 

Weight-based load balancing. New requests are sent to the server that's 
currently processing the least. 

Random load balancing. The next incoming request is sent to a server 
chosen at random. 

f Round-robin load balancing. The incoming request is given to the 
next server in line. Round-robin load balancing is the default balancing 
algorithm. 

WebLogic uses the round-robin load-balancing method by default. To use a 
different method, you must explicitly configure WebLogic as follows: 

1. Start Administration Console. 

For more information on this task, refer to Chapter 4. 

2. Select your cluster. 

On the left side of the screen, click the Clusters folder, and then click 
your cluster name. 

3. Select a load algorithm in the drop-down Default Load Algorithm list. 

4. Click Apply to save your changes. 



Configuring proxy plug-ins 

In addition to load balancing EJB and RMI requests, you may also want to 
load balance servlet and JSP requests. This is accomplished by using a proxy 
plug-in. A proxy plug-in sends, or proxies, requests from a web server to 
WebLogic Server instances in a cluster. In the process, the plug-in provides 
load balancing and failover for the proxied HTTP requests. This allows your 
JSP pages and servlets to be handled by multiple machines in your cluster. 

You can choose from two categories of proxy plug-ins: 

v* The WebLogic HttpClusterServlet plug-in 
V A third-party proxy plug-in 
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You set up HttpClusterServlet in this chapter. For third-party plug-ins, refer to 
their documentation. 
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proxy with your web application, you must first set up the proxy. 
The steps to set up HttpClusterServlet are summarized as follows: 

1. Create a web application that includes HttpClusterServlet. 

2. Create a deployment descriptor file. 

3. Create a web.xml file. 

4. Configure your application. 

For information on creating a web application, see Chapter 5. The deploy- 
ment descriptor file must contain the elements described in this section, 
specifically the servlet mapping and servl et tags. For more on creating 
descriptors, see Chapter 8. 

Step 3, creating a web.xml file that's designed to use the proxy, is covered 
next. Information on configuring web applications is in Chapter 4. 

To make use of the HttpClusterServlet proxy plug-in, you must add it to the 
<servl et> element of web.xml. The following code segment shows how to 
do this: 



<servl et-name> 
HttpCl usterServl et 
</servl et-name> 



<servl et-cl ass> 

weblogic.servlet.proxy.HttpClusterServlet 
</servl et-cl ass> 




Now you must map URLs to the proxy based on the file extension. This allows 
you to configure the proxy to handle *.jsp or *.html. 

If you set <url pattern) to/, you'll divert all requests that are not covered 
by another handler to the proxy. The following shows how to do this: 



<servl et-mappi ng> 

<servlet-name>HttpCl usterServl et</servlet-name> 

<url-pattern>/</url-pattern> 
</servl et-mappi ng> 

<servl et-mappi ng> 

<servlet-name>HttpCl usterServl et</servlet-name> 

<url-pattern>*.jsp</url - pattern) 
</servl et-mappi ng> 
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<servl et-mappi ng> 

<servlet-name>HttpClusterServlet</servlet-name> 
pattern)*. htm</url - pattern) 
1 et-mappi ng> 



<servl et-mappi ng> 

<servlet-name>HttpClusterServlet</servlet-name> 
<url -pattern>* .html</url-pattern> 

</servl et-mappi ng> 

Listing 16-1 incorporates this configuration into a complete web.xml file for 
proxy support. 



Listing 16-1: Sample web.xml for Proxy Support 

<!D0CTYPE web-app PUBLIC "-//Sun Microsystems, Inc. //DTD Web 
Application 2.2//EN" 

" http : // Java. sun. com/ j2ee/dtds/web-app_2_2 . dtd"> 

<web-app> 
<servl et> 

<servl et-name>HttpCl usterServlet</servl et-name> 
<servl et- 

class>weblogic.servlet. proxy. HttpClusterServlet</s 
ervl et-cl ass> 
<i nit-param> 

<param-name>WebLogicCluster</param-name> 

<param-val ue> 

myserverl:7736:7737|myserver2:7736:7737|myserver:7 

736:7737 
</param- val ue> 

</init-param> 

<i nit-param> 
<param-name>DebugConfigInfo</param-name> 
<param-value>ON</param-value> </init-param> 
</servl et> 

<servl et-mappi ng> 

<servlet-name>HttpClusterServlet</servlet-name> 
<url -pattern>/</url -pattern) 
</servl et-mappi ng> 

<servl et-mappi ng> 

<servlet-name>HttpClusterServlet</servlet-name> 

(continued) 
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attern>*.jsp</url -pattern) 
1 et-mappi ng> 




<servl et-mappi ng> 
<servlet-name>HttpClusterServlet</servlet-name> 
<url-pattern>*.htm</url-pattern> 
</servl et-mapping> 

<servl et-mappi ng> 

<servl et-name>HttpCl usterServl et</servl et-name> 
<url -pattern)* . htmK/url -pattern) 
</servl et-mappi ng> 

</web-app> 

You can use Listing 16-1 as a starting point for your own web.xml file. Listing 
16-1 supports JSP, HTM, and HTML files. You could add support for additional 
files simply by adding servlet mappings with the <servletmapping> tag. 



Configuring clustered JDBC 

Data access is usually a significant part of any WebLogic-based application. 
Because of this, you must properly cluster your data-related resources when 
clustering your server. In this section, you find out what you must do to keep 
your database connections compatible with your cluster. 

Two JDBC resources are commonly assigned to clusters: connection pools 
and data sources. When you create a connection pool or a data source, you 
assign it to a server, as discussed in Chapter 12. To use these resources with 
clustering, you simply assign them to a cluster rather than to a server. 

To use a connection pool or a data source with clustering, follow these basic 
steps: 

1. Create a connection pool. 

2. Assign the connection pool to the cluster. 

3. Create the data source. 

4. Assign the data source to the cluster. 

After you set up your connection, you're ready to use distributed JDBC. 
Clustered JDBC is accessed the same way as regular JDBC through WebLogic. 
The fact that you're using clustering is transparent to your application. 
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0 Tuning WebLogic Server 
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In This Chapter 

Using performance packs 
Changing thread settings 
Modifying JDBC and EJB performance settings 
Changing the startup script 
Switching your Java compiler 
••••••••••••••••••••••••••••••••••••••••••••••••a 

Ji/erformance is an important consideration in any enterprise application. 

W For your enterprise application to be successful, it must respond to user 
requests in a reasonable amount of time. Your application must hold up to 
even demanding heavy-use situations. 

You can increase the performance of your application in two primary ways: 
through the use of hardware and software. Using hardware to increase perfor- 
mance is covered in Chapter 16. In this chapter, you find out how you can use 
your existing hardware to increase performance by adjusting performance 
settings in WebLogic Server. 



WebLogic Server Performance Packs 

Java uses a virtual machine to execute its code, so Java code can execute on a 
variety of hardware platforms. The price for platform independence, however, 
is performance. To overcome this limitation in Java, you can use performance 
packs. 

WebLogic performance packs contain native code for specific hardware systems. 
Native code refers to low-level instructions unique to a given platform. Native 
code has been crafted to pull the most performance possible out of a platform. 

Most benchmarks provided by BEA show that you can reap major perfor- 
mance improvements by using native performance packs on machines that 
host WebLogic Server instances. These packs use a platform-optimized, 
native-socket multiplexor to improve server performance. However, if you 
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use a performance pack, you're no longer working in a "pure Java" environ- 
ment. This isn't usually an issue, unless you want to execute WebLogic on a 
^ I ^ ^^lj^^that doesn't have a native performance pack. 

In nearly all cases, you'll want to use a performance pack if one is available 
for your platform. Performance packs result in one of the easiest perfor- 
mance gains. 

Follow these steps to use a native performance pack: 

1. Make sure that your server is running. 

The server that you want to configure must be running. For a refresher 
on starting your server, see Chapter 3. 

2. Log on to Administration Console. 

Administration Console is usually at http : //l ocal host : 7001/consol e. 
For more information on Administration Console, see Chapter 4. 

3. Select your server. 

On the left side of the screen, click the Servers folder and then click 
your server. Your server's configuration page appears. 

4. Click the Tuning tab. 

The screen shown in Figure 17-1 appears. 



Figure 17-1: 

Tuning your 
server. 
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This page allows you to tune the performance and functionality of this server. 
0 Enable Native 10 

Specifies whether this server uses native I/O. 
Socket Readeis: 33 

The percentage (between 1 and 99) of execute threads from the default 
queue that this server may use as socket readers. (Allocating execute 
threads to act as socket reader threads increases the speed and the 
ability ofthe server to accept client requests.) This field is only relevant if 
you check the Enable Native IO box. 

Maximum Open Sockets: -1 
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5. Make sure that the Enable Native IO option is selected, and then 
click Apply. 



art your server. 

These changes take effect when your server is restarted. 



Thread Settings 

Threads are an important aspect of WebLogic. Many performance settings 
are related to threads. In this section, you work with some of the thread set- 
tings that you can use to improve WebLogic Server's performance. 



Setting thread count 

Requests to WebLogic are processed through execute queues. When you first 

install your server, you are given two execute queues named webl ogi c_ 

admi n_html_queue and webl ogi c_admi n_rmi_queue. These queues are 

reserved for communicating with Administration Console. If you don't config- 
ure additional execute queues, all web applications and RMI objects use the 
default queues. 

The size of the default execute queue is set to 15 threads. You can change 
this value if needed, but be careful. If you set this value too high, WebLogic 
spends most of its time switching between threads rather than performing 
real work. If you set the value too low, WebLogic may not be able to respond 
to requests in a timely manner. 

The value of the ThreadCount attribute of an ExecuteQueue element in 
the config.xml file equals the number of simultaneous operations that can be 
performed by applications that use the execute queue. As work enters an 
instance of WebLogic Server, it's placed in an execute queue. This work is 
then assigned to a thread. Threads consume resources, so handle the 
ThreadCount attribute with care — you can degrade performance by 
increasing the value unnecessarily. 




If native performance packs are not being used for your platform, you may 
need to change the default number of execute queue threads and the percent- 
age of threads that act as socket readers to achieve optimal performance. 



Thread count considerations 

Before you modify the thread count, you should consider several things. 
Simply adding threads to the queue will not necessarily increase perfor- 
mance. Although threads allow a program to do more than one thing at time, 
you're still ultimately limited by the processing power of your computer. 
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Two types of applications that often require more threads are 



dBooPS 



client applications that perform much of their processing on the 
ication server. 



V Applications in which the calls to the application server may take a long 
time to execute. This is because the calls are usually waiting on an exter- 
nal event, such as a database query. 



Determining an optimal thread count 

To determine the optimal thread count for an execute queue, monitor the 
queue's throughput while all applications in the queue are operating at maxi- 
mum load. Now increase the number of threads in the queue. At some point, 
you reach the optimal throughput for the queue. 

To monitor the throughput or change the number of threads, follow these steps: 

1. Make sure your server is running, and log on to Administration Console. 

2. Select your server. 

On the left side of the screen, click the Servers folder and then click 
your server. You now see your server's configuration page. 

3. Display the execute queues that can be modified. 

Click the Monitoring tab, which is shown in Figure 17-2. Then click the 
Monitor all Active Queues link. The screen shown in Figure 17-3 appears. 

4. Create and modify a queue as follows: 

a. Click the Configuration tab. 

b. Click the Configure a new Execute Queue link. 

This will allow you to create a new execute queue. From this 
screen you can specify the maximum and minimum number of 
threads. How to choose these values will be discussed next. 

c. Click Create. 

The screen shown in Figure 17-4 appears. 

d. Modify any of the parameters shown. 

5. Scroll down and click Apply to apply your changes. 

6. Restart your server. 

These changes take effect when your server is restarted. 
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£" WebLogic Server Console - Microsoft Internet Explorer 
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Figure 17-2: 
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your server. 
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As work enters a WebLogic Setver, it is placed in an e«e< 
that performs the work 

This page displays current runtime chaiacteiistics and statistics for the server's active execute queu 
is created for all new WebLogic Server instances WebLogic Server instances also contain two built- 

named web logic_admin_html_cjue.ue (available only on Administration Servers) and 

Heblogic_adKiin_rmi_queue. These queues are reserved for communicating with the WebLogic Server Administration 

Console; you cannot reconfigure these queues 
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£" WebLogic Server Console - Microsoft Internet Explorer 



Figure 17-4: 

The execute 
queue 
attributes. 
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As work enters a WebLogic Server, it is placed in an execute queue. This work is then assigned to a thread within the queue 
that performs the work. By default, a new WebLogic Server instance is configured with a default execute queue (named 
"default") that contains 15 threads. WebLogic Server instances also contain 2 built in execute queues named 

ueblogic_admin_html_queue and nehlogic admin rmi queue, but these queues are reserved for 

commun eating vvitii the Web Logic Server Administration Console. If you configure no additional execute queues, all Web 
applications and RMI objects use the default queue. This page allows you to configure a new, user-defined execute queue for 
use with applications on this server, or to edit an existing execute queue. 



Name: 



MyExecute Queue 



The name of this execute queue. 

Queue Length: j&5536 

The maximum number of simultaneous requests that this server can hold in the queue. 
Queue Length Threshold Percent 90 

The percentage of the Queue Length size that can be reached before this server indicates an overflow condition for 
the queue. 



Thread Count: |l5 

The number of threads assigned to this queue 
& Threads Increase: |0 

The number of threads to be added to the queue 
@S Threads Maximum: 400 



The maximum number of threads that this quei 



n have; this value prevents WebLogic Server fror 



£J Done 
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The number of CPUs in your system has a big effect on the number of threads 
that you should be using. Consider the following CPU scenarios: 

Thread count less than the number of CPUs. Your thread count may be 
too low. This is true if the CPU is waiting to do work, but there is work 
that could be done. Your thread count is too low also if you never reach 
100 percent CPU utilization rate. If this is the case, increase your thread 
count and compare performance results. 

Thread count equal to the number of CPUs. In theory, this is the ideal 
situation. It's most likely, however, that each CPU is underutilized. 
Increase the thread count and compare performance results. 

Thread count moderately larger than the number of CPUs. This could 
be an ideal setup if there is a moderate amount of thread switching and 
a high CPU utilization rate. If this is the case, tune the moderate number 
of threads and compare performance results. 

f Thread count greatly larger than the number of CPUs. An excess 

amount of thread switching is probably taking place, adding overhead to 
the system. Decrease the number of threads and compare performance 
results. 
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Detecting stuck threads 



ally, a thread becomes stuck — that is, it no longer executes additional 
en a thread is stuck, it's wasting system resources. The server can 
continue as long as all threads have not entered a stuck state. 

A thread can become stuck for many reasons. WebLogic Server automatically 
detects when a thread in an execute queue becomes stuck and gives the 
stuck threads a certain amount of time to continue. If the thread exceeds this 
amount of time, the thread is restarted. 

To configure WebLogic Server thread detection behavior, follow these steps: 



1. Make sure that your server is running, and then log on to 
Administration Console. 

2. Select your server. 

On the left side of the screen, click the Servers folder, and then click 
your server. You now see your server's configuration page. 

3. Click the Tuning tab. 

This tab was shown in Figure 17-1. 

4. Set the stuck thread properties. 

In the Stuck Thread Max Time box, type the maximum amount of time 
before the thread is restarted. In the Stuck Thread Timer Interval box, 
type the time between the thread scans. 

5. Restart your server. 

These changes take effect when your server is restarted. 



JDBC Performance Settings 

Most enterprise applications use the database and JDBC for their data 
access. Because of this, you can achieve great performance gains by simply 
setting up the JDBC performance settings properly. 



JDBC connection pools 

You should always use JDBC connection pools when accessing databases 
from server components such as EJBs. It's easy to set up connection pools 
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using Administration Console. For more information on setting up a JDBC 
connection pool, see Chapter 12. 



connection to a database, a certain amount of overhead is incurred. 
This can add up considerably if many connections are opened to the same 
database. A connection pool opens up multiple connections to a database, 
and the EJBs share this access. 



You have the option of setting how many connections a pool allows. The pool 
can grow and shrink between the configured minimum and maximum values. 
In general, the best performance occurs when the connection pool has as 
many connections as there are concurrent client sessions. 



Connection pool initial capacity 

Connection pools have a defined initial capacity. This value represents the 
smallest number of connections that the pool can have. 




If you set the connection pool initial capacity too high and WebLogic can't 
initialize that number of connections, the connection pool fails to start. 



During development, you may want to set the pool initial capacity lower so 
that the server starts faster. 



Pool maximum capacity 

The pool maximum capacity specifies the maximum size that a connection 
pool can reach. 

In production systems, the pool maximum capacity and the initial capacity 
are often set to the same number. This causes the server to create all connec- 
tion objects immediately. 



Caching prepared statements 

The prepared statement object allows you to define SQL with parameter 
values. In this way, JDBC can compile the SQL statement once and use the 
object to execute the statement over and over. However, it's not always the 
same statement, because of the parameters you can specify. To create a pre- 
pared statement, you use the PreparedStatement class. 

WebLogic caches these prepared statements so that they don't have to be recre- 
ated each time they're used. You can define the size of this cache of prepared 
statements. If you set the value too low, prepared statements are not cached. 
If you set the value too high, the system is processing needless overhead. 
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major component of WebLogic, and you can set many performance 
options for them. These settings are stored in the weblogic-ejb-jar.xml deploy- 
ment file, which contains information specific to WebLogic Server. It contains 
also the descriptors that map available WebLogic Server resources to EJBs. 
WebLogic Server resources include security role names and data sources such 
as JDBC pools, JMS connection factories, and other deployed EJBs. 

Like any other XML file, the weblogic-ejb-jar.xml file can be loaded with a reg- 
ular text editor. To change parameters in the file, you use the editor, save the 
file, and then restart WebLogic Server. 



Setting EJB pool size 

For every stateless session bean class, WebLogic keeps a free pool for EJBs. 
The max-beans- in-free-pool element of the weblogic-ejb-jar.xml file speci- 
fies the size of this pool. The default is no limit, which means the pool is limited 
only by available memory. 

You shouldn't change the value of the maxbeansin-freepool parameter 
unless your program frequently creates session beans and then discards 
them. If this is the case, enlarge the free pool by 25 to 50 percent and see 
whether performance improves. If object creation represents a small fraction 
of your workload, increasing this parameter will not significantly improve 
performance. For database-intensive EJBs, do not change the value of this 
parameter. 

Tuning max-beans - in-free-pool too high uses extra memory. Tuning it too 
low causes unnecessary object creation. If in doubt, leave it unchanged. 

Allocating pool size for session and 
messaqe beans 

When an EJB is created, the session bean is given an identity. When the client 
program removes this bean, it's placed back in the free bean pool. When sub- 
sequent beans of the same type are created, the original bean is used, thus 
saving the overhead of recreating the bean. The max-beans - in-free-pool 
element, which controls the size of this pool, can improve performance if the 
same EJBs are frequently created and removed. 
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EJB instances are created as needed by the container for message process- 
ing. The max beans in pool element establishes an absolute limit on the 
f these instances created. WebLogic may override this setting 
to available runtime resources. 



In general, for the best performance when using stateless session and message 
beans, you should use the default setting for the max- beans -i n -free-pool 
element. The default is optimized to allow you to run beans in parallel, using as 
many threads as possible. The only reason you would change this setting is to 
limit the number of beans running in parallel. 



Allocating pool size for anonymous 
entity beans 

Anonymous entity beans are beans without a primary key assigned to them. 
The max-beans - in-free-pool element controls the size of not only the free 
bean pool but also the pool of anonymous entity beans. If you're running 
many finders or home methods or creating lots of beans, you may want to 
tune themaxbeans - infreepool element so that enough beans are avail- 
able for use in the pool. 



Tuning initial beans in the free pool 

The initial-beans-in-free-pool element of the weblogic-ejb-jar.xml file 
specifies the number of stateless session bean instances in the free pool at 
startup. If you specify a value forinitialbeansin-freepool, WebLogic 
Server populates the free pool with the specified number of bean instances. 
Populating the free pool ahead of time is a way to improve initial response 
time for the EJB, because initial requests for the bean can be satisfied with- 
out generating a new instance. 



Setting EJB caching size 

WebLogic Server allows you to set the number of active beans present in the 
EJB cache. The m a x - b e a n s - i n - c a c h e element of the weblogic-ej b-j ar.xml file 
specifies the maximum number of objects of this class that are allowed in 
memory. The value of this element sets the cache size for both stateful session 
and entity beans. 
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WebLogic requires that you specify certain Java parameters when it starts. 
For simple startups, you can specify these parameters on the command line. 
However, WebLogic usually requires many parameters, so using a script 
makes more sense. (For more information about starting WebLogic, see 
Chapter 3.) 

Two startup scripts are automatically provided when you install WebLogic. The 
Administration Server scripts are startWLS.sh (UNIX) andstartWLS.cmd 
(Windows). These two scripts are in the WebLogic bi n directory. 

You can modify some of the default Java values in these scripts to fit your 
environment and applications. The important performance-tuning parameters 
in these files are the JAVA_H0ME parameter and the Java heap size. Change the 
value of the JAVA_H0ME variable to the location of your JDK. For example: 



JAVA_HOME=C: \bea\jdkl31_03 






For even higher performance throughput, set the minimum Java heap size 
equal to the maximum heap size. For example: 


"%JAVA HOME°Abin\java" -he 
%CLASSPATH% - 


itspot -Xrri! 


5512m -Xmx512m -c 


1 asspath 









Setting \lour Jatfa Compiler 

JSP pages and servlets must be compiled on-the-fly, as they're needed by a 
WebLogic process. By default, the standard Java compiler is used. You can 
improve performance significantly by setting your server's Java compiler to 
one that's faster than Sun's javac. One common replacement is IBM's jikes: 

http://oss.ibin.com/developerworks/opensource/jikes 

Follow these steps to change your compiler: 

1. Make sure that your server is running, and log on to Administration 
Console. 

2. Select your server. 

Click the Servers folder, and then click your server. 
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3. Click the Compilers tab. 

4. In the Java Compiler box, type the full path to your compiler. 



In the Append to Classpath box, type the full path to the JRE rt . j a r 
library. This allows you to access the runtime library from Java. 

6. Click Apply. 

7. Restart your server. 

Now you know some of the software items that you can configure to make 
your application run faster. In addition to the software changes that you can 
make, you've seen how you can tune WebLogic at the server level. 




ify the library location. 
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In This Chapter 

Reviewing WebLogic security 
Uncovering the Secure Socket Layer (SSL) 
Entering the user realm 



Security is an important part of any web application. You've probably 
read some of the highly publicized cases of corporate computer systems 
compromised by hackers. Many more go unreported. In this chapter, you find 
out how to use some of the many features in WebLogic that help you enhance 
the security of your application. 



Understanding WebLogic Security 

WebLogic has many built-in features to enhance security but you must be 
aware of them to properly defend your system. Many of these security fea- 
tures must be customized to suit your particular application. Security is not 
automatic; you must take steps to ensure that your system is secure. 

WebLogic's security architecture is open and flexible. It delivers advantages 
to all levels of users and provides an advanced security design for applica- 
tion servers. 

In this chapter, you examine some of the common security features of 
WebLogic. For information on features not covered here, refer to the online 
help included with WebLogic. 



Secure Sockets Lager (SSL) 

Secure Socket Layer (SSL) is one of the most common forms of web security. 
SSL is usually used through Hyper Text Transfer Protocol Secure (HTTPS). If 
you log on to almost any financial web site to check your account, for example, 
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you'll see the URL change to one that begins with https. HTTPS and SSL provide 
the following advantages: 



verification 
V Data encryption 

HTTPS allows you to be sure that you're connecting to the intended host. If 
you enter the URL https : //www. webl ogi c . com, for example, SSL ensures 
that you're using that site. A domain name such as http : / / www . webl ogi c . 
com is mapped to an IP address by domain name service (DNS). If a hacker 
tampers with the DNS, you could be taken to an IP address other than the one 
you were expecting. SSL ensures you're accessing the correct IP address, 
which ensures that you're accessing the correct server. 

Data encryption is another valuable feature provided by SSL. If you log on to 
your bank's web site to view your account, for example, you must enter your 
user ID and password. Without SSL, this user ID and password would be 
transmitted, unencrypted, across the Internet. Your password and ID could 
be intercepted by a malicious user. SSL encrypts your password and user ID 
so that they're not visible to someone monitoring the packets between the 
user and web server. 



Setting up SSL on WebLogic Server involves a number of steps. These steps 
are summarized here and explained in more detail in the next sections: 



1. Obtain an identity and a trust. 

An identity is a private key and a digital certificate. The trust is a certificate 
issued to you by a trusted certificate authority (CA). Digital certificates, 
private keys, and trusted CA certificates can be obtained from the 
WebLogic Server kit, the Cert Gen utility, Sun Microsystem's keytool 
utility, or a reputable certificate authority such as Entrust or Verisign. 

2. Store the keys and certificates. 

You must store the private keys, digital certificates, and trusted CA cer- 
tificates in a location accessible by WebLogic. Digital certificates are 
stored in a file in the domain directory of WebLogic Server. Private keys 
and trusted CA certificates are stored in a keystore. 

3. Enable SSL on your server. 

You must set SSL attributes for the server's identity and trust locations 
in WebLogic Server's Administration Console or in a server start script. 
The SSL attributes define the location of the private key, digital certifi- 
cate, and trusted CA certificates. 
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Obtaining an identity 



step in setting up SSL on WebLogic Server is obtaining a certificate 
rtificate authority. This CA certificate, which contains your key, is 
used to ensure web visitors that you really are who you say you are. 
WebLogic includes a tool to help you generate a request form that can be 
used to obtain a certificate from a CA. To use this tool, follow these steps: 



1. Make sure that your server is running. 

The server that you want to configure must be running. For a refresher 
on starting your server, refer to Chapter 3. 

2. Log on to Certificate Generator. 

Certificate Generator is usually athttp://localhost:7001/ 
certificate. You have to enter the administrator user ID and 
password. The screen shown in Figure 18-1 appears. 

3. Enter the required information. 

Scroll down so that you can see the form for entering information about 
your web site. Figure 18-2 shows how I filled out the form for my web site. 



Figure 18-1: 

Certificate 
request 
generator. 



S|] BEA WebLorjic Server Certificate 

File Edit View Favorites Tools Help 



enerator - Microsoft Internet Explorer 

QBack • 0 • [K] ^ I , Search Favorites Media •© 0 ' ^ S 
Address Ifp http;//localhost:700i;certiricate 




BEA WebLogic Server Certificate Request Generator 



Fill out all of the fields on this form. All fields are required The information entered should contain only 
alphabetical or numerical characters when specifying country code, organizational unit name, organization 
name, locality name, and state name. The Private Key Password will need to be provided when booting a 
server if using the private key and certificate generated using this request.You cannot abreviate anything, 
except that you must use a valid country code When vou have completed the form, click the "Generate 
Request" button 

After validating the form, WebLogic Server generates a public/private key pair and a Certificate Signing 
Request (CSR), which includes the public key and the information you provide in this form Three files are 
saved in the WebLogic Server startup directory: your private key and the CSR in two formats. The CSR is 
saved in a binary format and in an ASCII PEM (privacy-enhanced email) format. The servlet displays the CSR 
in its PEM format. You can copy this directly from your browser and submit it to a Certificate Authority to 
request your new certificate 

Be sure to save and backup the private key. It is your WebLogic Server's secret, and you should keep it in a 
safe place. Be sure to remember the password to your private key. 

After the private key and CSR have been generated, you can submit your certificate request to VeriSignfor a |v] 



5tart Server -C:\bea.. 



3 BEA WebLogic Server... 
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Figure 18-2: 
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Country code 



us 

Example: US 



Research 

Organizational unit name 



Example: Research 



Organization name 



Email address 



Full host name 



Jeff Heaton. Inc 



Example: BigCo, Inc. 



heatonj@jeffheaton.com 

Example: me@bigcoinc.com 



ljefftiBaton.com 

Example: myhost.bigcoinc.com 



Locality name (city) 



State name 



Private Key Password 



| Chesterfield 

Example: Northeast Pampasville 



Missouri 



Example: Florida 



joshuaj 



gj http://localhost:7001/certificate/help/CertificdteHelp.htrnl#keyPassword 
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Start Server -C:\bea.. 



3 BEAWebLogic Server... 
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4. Click Generate to generate a certificate. 

The screen shown in Figure 18-3 appears. This is the request certificate 
that you send to a certificate authority, such as Verisign. 

After you obtain your certificate, you must store it into the keystore. This is 
explained in the next section. 



Storing keys and certificates 

Certificates must be stored in a keystore. The keystore is managed using the 
Java key tool command. If you've added the WebLogic bi n directory to your 
path, you can access the keytool command from the command prompt. 
Some of the common tasks that you can perform with the keytool command 
are described next. 
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Figure 18-3: 
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: 7001 /certificate 
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BEA WebLogic Server Certificate Request Generator 



BEGIN NEW CERTIFICATE REQUEST 

HIIBYTCCAQsCAQAwgaUxFzAVBgNVBAHTDiiiplZiriZQZtiIF0b24uY29tHQswCQYDVQQGEwJVUzEV 
HBHGAlUEBxHHQ2hlc3RlcrriZpZ¥xkHREwDwYDVQQIEwhNaXNzb3VyaTEZHBcGAlUEChHQSttiViti 
ZiBIZMF0b2 4sIEluYzERMA3GAlUECxHIUiriVzZWFyY2gxJTAjBcjkcjhkiG9wDBCQEWFitihlYXRv 
briipAairiVitiZnihlYXRvbi5jb20MXDANBgkqhkiG9wOBAQEFAANLADBIAkEA2ffpgWdocbUpN/vL 
SSH3+d69gf XLFDlpk44T18qJZwF/ iOvOKNPZf XLLn4rnxDxWHpUt lszboVqqvf AEussbNQID 
AQABoAAxjDQYJKoZIhvcNAQEFBQADQQDILM6aHwyFQVqeucpkUH10RF/rFRDt.eAGZvZuisuFL 
dxruj h54uUugGXVI+afc7QynCFscrjZlVdxFFYhP/X6j 
END NEW CERTIFICATE REQUEST 

Protected Key filename:C:\bea\user_projects\mydomain\jefflieaton_com-key.der 
Request filename:C:\bea\user_projects\mydomain\jefnieaton_com-request.pem 



I Submit | Certificate Signing Request to VeriSign for a Test Digital ID 

This button produces a test certificate. To obtain a formal server certificate from VeriSign, follow the steps at 
http://diaitalid.verisian.com/sen/er/trial/triallntro.htm 

I Submit | ppttifir^tP Sinninn RpniiPQt tn Raltimnrp's CvherTri ist Si ire Server fnr a fnrrnal Wphl nnir Spn/Pf v 



£ Done 
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Creating a kegstore 

The first thing you should do is create a new keystore for WebLogic's use. You 
need to do this only once. To create the keystore, use the following command: 

keytool -genkey -keystore keystorename -storepass 
key store pas sword 

Replace keystorename with the path and file name of the file you want to use 
as the keystore. The keystore also needs to have a password, which you 
should use in place of keystorepassword. You'll use that password to 
access the keystore. 

Loading a private keg 

When you ran the certificate generator in the preceding section, one result 
was that a private key was generated in a file whose name ends in the .pern 
extension. This file should be added to the keystore using the following com- 
mand line: 
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keytool -alias al 7 asforpri vatekey -import -file 

pri vatekeyfi 1 e .pem -keypass pri vatekeypassword - 
keystore keystorename -storepass keystorepassword 



To add the private key, you need to know the file name of the keystore 

{keystorename} and its password {keystorepassword}. You also need 
the name of the file containing the private key (pri vatekeyfi le .pem) and 
the password for that file {pri vatekeypassword}. You also specify an alias 
{a 7 7 asforpri vatekey} by which this private key will be known in the 
keystore. 

When you're finished adding a private key to your keystore, copy the .pem 
file to a backup device (such as a floppy disk) and store it someplace safe. 
You'll need this file if your keystore becomes damaged. 



Loading a trusted CA certificate 

When a certificate is granted to you by a certificate authority, you need to 
load that certificate into the keystore. To do so, use this command line: 

keytool -alias al i asfortrustedca -trustcacerts -import -file 
trustedcafilename.pem -keystore keystorename - 
storepass keystorepassword 

Again, you use keystorename and keystorepassword to specify the key- 
store's location and password, respectively. You also need to specify an alias 
by which the certificate will be known in the keystore {a 7 i asfortrustedca} 
and the path and file name of the certificate file (trustedcafi 7 ename . pem). 



Displaying keystore contents 

To display the complete contents of the keystore, use the following command: 

keytool -list -keystore keystorename 

Deleting a keg 

To delete a private key that you no longer need, use the following command. 
You delete a key by referring to its alias: 

keytool -keystore keystorename -storepass keystorepassword - 
delete -alias al i as forpri vatekey 
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You can't undo a delete operation. If you decide you still want to use the pri- 
vate key you must add it to the keystore again. (This is one reason why you 
ore the .pern file for the private key on a floppy disk and put it in a 

) 



Displaying help 

If you need a short refresher on how to use keytool, use the following 
command: 

keytool -help 



Enabling SSL on your seri/er 

Now that you have obtained the needed certificates, you can enable SSL in 
WebLogic. Follow these steps: 

1. Make sure that your server is running. 

The server that you would like to configure must be running. For a 
refresher on starting your server, refer to Chapter 3. 

2. Log on to Administration Console. 

Administration Console is usually athttp://localhost:7001/ 
con so 1 e. If you need a refresher on getting into the administration 
console, refer to Chapter 4. 

3. Select your server. 

Click the Servers folder, and then click your server's name. 

4. Configure SSL. 

Click the Keystores & SSL tab. The screen shown in Figure 18-4 appears. 
Provide the alias that you used for your certificate when you added it to 
your keystore. 

5. Change your keystore. 

WebLogic uses a demo keystore by default. When you want to specify 
your own keystore, click the Change link in Figure 18-4 and configure the 
keystore. 
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e] Applet navapplet started 



Connected to : localhost 7001 



You are logged in as : admin 



| Protocols | Logging | Monitoring | Control | Deployments 



Genera^^Cluste^PtKeystores&SSL^^ 

A Keystore is a mechanism designed to create and manage files that store private keys 
trusted certificate authorities (CAs) for use with SSL. This page allows you to view and c 
various Keystore configuration and Secure Sockets Layer (SSL) settings for this server, 
settings help you to manage the security of message transmissions. 



Keystore Configuration 

Identity 

Demo Identity Keystoie: 



[ Change 1 



$BEAHOME\server\lib\Dernoldenti 



Indicates the use of the identity (private key) keystore provided by WebLogic 
Server. The identity keystore is located in 

WL_HOME\server\ lib\ Dernoldentity . jks. This keystore is configurer, 
default. 
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Introduction to Security Realms 

WebLogic allows you to lock down certain resources of WebLogic called secu- 
rity realms. You can create users, groups, and roles to manage access to the 
following security realms: 

is* Administrative resources such as the WebLogic Server Administration 
Console 

i>* Enterprise applications 

u* Component Object Model (COM) resources 

V Enterprise Information System (EIS) resources 
Enterprise JavaBean (EJB) resources 

v 0 Java DataBase Connectivity (JDBC) resources 

V Java Naming and Directory Interface (JNDI) resources 
Java Message Service (JMS) resources 

MBean resources 
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V Server resources related to WebLogic Server instances, or servers 
URL resources related to web applications 



services resources 



You can control access to each of these resources by using Administration 
Console. You discover how to secure these resources later in the chapter. Next, 
you find out how to create the different entities that inhabit security realms. 




Users 



Users are the most basic type of entity that can be authenticated in a 
security realm. A user is not necessarily a person. User are typically one of 
the following: 



A developer or an administrator 
v* An application end user 
j>* A client application 

Other instances of WebLogic Server 



When a user wants to access a specific resource, the user must be authenti- 
cated in one of two ways: 



f" Using a password 

V Using a digital certificate 



Just like groups, users must have unique names. Further, a user and a group 
may not have the same name. 

Follow these steps to create a user: 

1. Make sure that your server is running, and log on to Administration 
Console. 

2. Select the Users folder. 

Click the following folders: mydomain, Security Realms, myrealm, and 
then Users. The screen shown in Figure 18-5 appears, listing all current 
users. 

3. Click the Configure a new User link. 

The screen shown in Figure 18-6 appears. 
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Figure 18-5: 
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gj Applet navapplet started 



Connected to : localhost 7001 



Vo. ate logged in a = admin 



Users are entities that can be authenticated. A user can be a person or software 
entity, such as a Java client. Each user is given a unique identity within a security 
realm. BEA recommends assigning users to groups for two reasons: it makes the 
WebLogic Security Service perform better, and makes it more efficient for 
administrators who work with large numbers of users. 

This Users page displays key information about each user that has been configured i 
this security realm. 

^Configure a new User... 



Filter By: 



Filter 



User 


Description 


Provider 


admin 


DefaultAuthenticator 0 



< 
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Figure 18-6: 

A new user. 
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myrealm> Create User 

Connected to : localhost :7001 | You are logged in as : admin | Logout 



| Groups | Details j 



This page allows you to define a user in this security realm. 
Name: 



new user 



The login name for this user. 

Description: | | 

A short description of this user. For example, the user's full name, 

Password: 



Confiirn 
Password: 



The password associated with the login name for this user. 



Apply 



L<1 
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4. Create the user. 
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Type a name and password for the user. (You must type the password 
e: once in the Password box and once in the Confirm Password box.) 
click Apply. 

5. Assign the user to one or more groups. 

Click the Groups tab. The screen shown Figure 18-7 appears. Assign the 
user to whatever groups you want. Then click Apply. 



Groups 




A group is another entity used in a domain. A group is made up of users that 
have something in common. These users usually share a common level of 
access. This allows the WebLogic administrator to quickly assign users to the 
correct groups. It's much more efficient to manage a large number of users 
through the use of a group. 

Just like users, a group must have a unique name. Further, a user and a group 
can't have the same name. 



Figure 18-7: 

Assign 
groups. 
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General KcffrrnT^ Details 



You are logged in as : admin 



This page allows you to select the groups to which this user belongs. 



Possible 
Groups 



Group Membeiship: 



Administrators 
Deployers 
Monitors 
Operators 



Current 
Groups 



S 



a 
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Groups enable you to quickly configure settings for many users. 

' Cjl^^S) a new § rou P' f°U° w these steps: 

1. Make sure that your server is running, and log on to Administration 
Console. 

2. Select the Groups folder. 

Click the following folders: mydomain, Security, Realms, myrealm, and 
then Groups. The screen shown in Figure 18-8 appears, listing all current 
groups. 

3. Click the Configure a new Group link. 

The screen shown in Figure 18-9 appears. 

4. Create a group. 
Type a name for the group, and then click Apply. 

5. Assign other groups to the group. 

Click the Membership tab. The screen shown in Figure 18-10 appears. 
Assign another group or groups to this group. For example, if you want 
everyone in this group to be an administrator, assign the Administrators 
group to the Current Groups list. 



Figure 18-8: 

Realm 
groups. 
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Filter By: 



Group 


Description 


Provider 




Administrators 


Administrators can view and 
modify all resource attributes 
and start and stop servers. 


DefaultAuthenticator 


a 


Deplovers 


Deployers can view all 
resource attributes and 
deploy applications. 


DefaultAuthenticator 


0 


Monitors 


Monitors can view and 
modify all resource attributes 
and perform operations not 
restricted by roles 


DefaultAuthenticator 


a 


Operators 


Operators can view and 
modify all resource attributes 
and perform server lifecycle 
operations. 


DefaultAuthenticator 


0 
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Connected to : localhost :,'001 I Vou ate logged in as admin | Logout 



Membership | Details 



This page allows you to define a group in this security realm. 
Name: new_group 
The name for this group 

Description: | | 



A short description of this group. 



Apply I 
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Figure 18-10: 

Assigning 
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groups. 
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myrealm> Group 

Connected to : localhost 7001 



I You are logged in as : admin | Logout 



[^ Configure a new Group.,. 
General \ Details 



Select the groups to which this group belongs. 



Possible 
Groups 

Administrators 
Deployers 
Monitors 
Operators 



Group Membership: 



Current 
Groups 







a 
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oles grant privileges to users and groups based on specific condi- 
e groups, security roles allow users to be grouped. Unlike groups, 
however, security roles are calculated dynamically, as the server runs. 

To create a security role, follow these steps: 

1. Make sure that your server is running, and log on to Administration 
Console. 

2. Select the Global Roles folder. 

Click the following folders: mydomain, Security, Realms, myrealm, and 
then Global Roles. The screen shown in Figure 18-11 appears, displaying 
all current roles. 

3. Click the Configure a new Global Role link. 

The screen shown in Figure 18-12 appears. 



Figure 18-11: 

Realm roles. 
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specifies who has what access to the WebLogic resource. 

Global roles, the types of security roles you work with here, are security roles that 
apply to all WebLogic resources in a security realm. You can also create scoped 
roles, or security roles that apply to a specific instance of a WebLogic resource (such 
as a method of an EJB or a branch of a JNDI tree), by right-clicking the WebLogic 
resource. 

This Global Roles page displays key information about each global security role that 
has been configured in this security realm. 
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Role 


Provider 




Admin 


DefaultRoleMapper 


a 


Anonvmous 


DefaultRoleMapper 


a 


DeDlover 


DefaultRoleMapper 


a 


Monitor 


DefaultRoleMapper 


a 


Ooerator 


DefaultRoleMapper 


a 
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Figure 18-12: 

A new role. 
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A security role is an abstract, logical collection of users that is similarto a 
group. The difference between groups and security roles is that a group is a 
static identity a server administrator assigns, while membership in a security 
role is dynamically calculated based on data such as username, group 
membership, or the time of day. Security roles are granted to individual users 
or to groups, and multiple security roles can be used to create security 
policies for a WebLogic resource. 

A global role is a security role that applies to all WebLogic resources within a 
security realm. This page allows you to define a global role in this security 
realm. 







Name: new_role 




The name of this globa 


role. 
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4. Create a role. 

Type a name for the role, and then click Apply. 

5. Create conditions. 

Click the Conditions tab. The screen shown in Figure 18-13 appears. 
Assign any of the following conditions, and then click Add: 

• User name of the caller. You can require that the user's name is a 
certain value. If you select this option, you're prompted for the 
user name that you want to compare against. 

• Caller is a member of the group. You can require that the user be 
a member of a certain group. If you select this option, you're 
prompted for the group name that you want to compare against. 

• Hours of access are between. You can specify a range of time 
during which the system can be accessed. If you select this option, 
you're prompted for the time range. 
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Connected to : localhost 7001 | You are logged in as : admin | Logout 
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Details | 



Use the Role Condition box to select a condition that must be met for 
users/groups to be considered "in" this security role. Click Add to provide the 
specifics for the Role Statement and if necessary, reorder the role statements 
using the Move Up/Move Down buttons. You can also edit or remove role 
statements by clicking the individual Role Statement and then the Edit... or 
Remove buttons. Be sure to click Apply when you are finished. 

Role Condition: 



[<J_ 



User name of the caller 
Caller is a member of the group 
Hours of access are between 
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Security policies 



Security policies are the connection between WebLogic resources and users, 
roles, and groups. Using security policies, you can define which resources are 
available to which users, and under what conditions. 

Security policies, introduced in WebLogic Server 7.0, replaced access control 
lists (ACLs), a feature in WebLogic Server 6.x. 

Security policies are not configured from one central location in 
Administration Console. Rather, you can right-click nearly any resource in the 
Administration Console tree and set up a policy for it. 

To create a security policy, follow these steps: 

1. Make sure that your server is running, and log on to Administration 
Console. 

2. Select the resource for which you want to set a policy. 

To follow along with the example, select the EJB Modules folder. To do 
so, click the following folders: mydomain, Deployments, and then EJB 
Modules. 
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3. Define a policy. 

|— ^ ■ Right-click EJB Modules, and choose Define Security Policy. The screen 

1 1T\ f\ L^s^^vn in Figure 18-14 appears. Choose one or more of the following poli- 

L-^ I V/ yj I—/ \J \J I \V? and then click the Add button: 

• User name of the caller. Allows you to require that the user's 
name is a certain value. If you select this option, you're prompted 
for the user name that you want to compare against. 

• Caller is a member of the group. Allows you to require that the user 
be a member of a certain group. If you select this option, you're 
prompted for the group name that you want to compare against. 

• Caller is granted the role. Allows you to specify a role that the 
caller must match to be able to access the specified resource. If 
you select this option, you're prompted for the role that you want 
to compare against. 

• Hours of access are between. Allows you to specify a range of 
time that the system can be accessed. If you select this option, 
you're prompted for the time range during which this resource 
will function. 



For the user to be able to access the resource, all specified conditions 
must be met. 



Figure 18-14: 

Define a 
security 
role. 
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Define Security Policy > Default EJB 



Connected to : localhost 7001 | You are logged in as : admin | Logout 



Use the Policy Condition box to select a condition that must be met for the security 
policy to be created. Click Add to provide the specifics for the Policy Statement and if 
necessary, reorder the policy statements using the Move Up/Move Down buttons. You 
can also edit or remove policy statements by clicking the individual Policy Statement 
and then the Edit... or Remove buttons. Be sure to click Apply when you are finished. 

The information presented below may not be 
accurate. To ensure that you are viewing accurate 
information, you may need to delete and redeploy 
your WebLogic resources. 
Policy Coiulition: 



r 



User name otthe caller 
Caller is a member of the group 

Caller is granted the role 
Hours of access are between 
Server is in Development Mode 



Add 
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You've examined how to define a policy for a web resource. You can also 
modify the policy of nearly every folder in the Deployments folder. 



n see from this chapter, WebLogic provides a number of security 
features. You saw how SSL can make transmissions to and from the server 
more secure. You also saw how realms can control how WebLogic resources 
are accessed. 
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In this part . . . 

■ Wver time, you'll discover many techniques pertaining 
to WebLogic and programming in general. Here, I pass 
along some of these techniques that I've found while work- 
ing with WebLogic. I provide ten suggestions for developers 
and administrators as well as ten suggestions to follow 
before going live with your application. 













Chapter 19 

Practices for Developers 



In This Chapter 

Keep adequate documentation 

Use Usenet 

Don't over-engineer 

Isolate development, testing, and production 

Know what you're developing 

Take the time to understand tools 

Create modular, decoupled applications 

Be mindful of security 

Test your software 

Manage your build process 



I\ s a WebLogic developer, it's important to know how to structure your 
¥ \ applications and development environment. You must also know how to 
reach out to the WebLogic community when you run into problems. In this 
chapter, I discuss these recommendations and other information that has 
helped me over the years as a developer. 



Keep Adequate documentation 



Documentation is an important part of any application. As a developer, you 
should do your part to ensure that your application is properly documented. 
Documentation falls into several categories: 



i>* Program code documentation. The most obvious form of documentation 
consists of the comments in the source code. Javadoc is a good way to 
provide this documentation. 
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i>* Developer handbook. A basic but often overlooked use for documenta- 
tion is bringing new programmers up to speed. On mature applications, 
lopers' computers often contain a mix of files used as the application 
developed. This environment can be difficult for a new developer to 
recreate. The developer's handbook describes the process needed to set 
up the development environment on a new machine. 

f" Program specification. Changes to the specifications of your application 
must be communicated to all who are involved in these changes. 

End user documentation. This is the documentation that your users 
refer to for information on how to use your system. As features are 
added to the system and existing features changed, make sure that you 
update the user documentation. 

By keeping all forms of documentation properly maintained, developers and 
users can stay current with the application. 



Use Usenet 

One of the greatest benefits of the Internet is the sense of global community 
And no single portion of the Internet embodies this more than Usenet, which 
consists of a large collection of messages posted by Internet users on a variety 
of topics. 

You can access Usenet in several ways. You can install client programs that 
download and filter Usenet postings for you. You can also use web-based 
portals. One of the most common web portals is Google, at http : //groups . 
googl e .com. 



Don't Over -Engineer 

WebLogic provides you with a wealth of technologies. EJBs allow you to dis- 
tribute your processing tasks and skip writing database caching code. Web 
services allow you to make your application available over a standard SOAP 
interface. XML allows you to design standard content structures for your data. 

However, you should avoid the temptation to use a technology just because 
WebLogic makes it available. For example, web services have a specific pur- 
pose. They enable you to expose your application to other applications that 
must use it across the Internet. In general, web services shouldn't be used 
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internally by your application. I came across an application that used web 
services for all communication between the back-end EJB components and 
end JSP pages. This resulted in many web service calls for each dis- 
ge, a slow process that led to bottlenecks and an overall poor site. 



Set Up Development Environments 

WebLogic allows you to create multiple servers that run from the same 
machine. This provides a convenient way to provide several development 
environments, such as the following: 

Development. The development environment is where developers test 
their code. This allows developers to test their code in a controlled envi- 
ronment. Stable versions on the development server are usually rolled 
over to the test server. 

Test. Your project team will likely consist of quality assurance (QA) people 
who test the software and report new bugs. QA people shouldn't be test- 
ing from your development server because the server is too volatile. 
Rather, you should roll out a stable version from your development server 
to the test server. This version can then be tested by your QA staff. 

v 0 Demo. You'll have to demo your software, either to clients to show the 
progress of the system you're creating, or to internal users who will 
soon be using your system. If you don't create a demo server and a 
developer destabilizes your development server, your demo is shot. 

Documentation. It's likely that a group of people will be creating the 
documentation for your application. They'll be logging on to the server 
and taking screen shots and performing other activities related to the 
end-user documentation. It is important to give your tech writers a 
stable environment from which to develop their documentation. 

Beta. When you think that your application is ready for production, have 
your end users test the software one final time before it's rolled out to 
production. This process is called end user acceptance testing. It's a good 
idea to perform this testing from a special beta server. 

Production. The production version of your program is the one that's 
used by end users. It's up to your server administrators to make sure 
that the production server stays available to them. This will be the last 
stop that any version of your software is rolled to. 

It's not necessary to set up all these environments on different machines. 
Several of these environments can be combined on a single machine. 
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loper, you should understand the problem you're trying to solve. 
This may seem obvious, but developers on large applications can easily lose 
sight of the goal for several reasons: 

Unclear program specifications 

Developers who are aware of only their own local areas of the program 
*** Poor access to business users who understand the specifications 



Understand the Tools 

Many tools are available to make the developer's life easier. Unfortunately, 
you can spend a lot of time learning to use these tools before you realize any 
gain in programming time. In effect, your time to learn a tool is an investment. 
A developer should at least have the following tools: 

A text file editor 

V An integrated development environment (IDE) that supports debugging 

V A build tool, such as ANT 
A source code beautifier 

i>* WebLogic Resource Workshop 

V Version control 



Create Modular, Decoupled Systems 

A large application will have many classes and intertwined systems. Creating 
a system comprised of many modules has several advantages: 

f Common modules can be reused. 

The program is easier to understand because large problems are broken 
into many smaller problems. 

Different programmers can be working on different modules without 
interfering with each other. 



Chapter 19: Ten Best Practices for Developers 



325 



maintenai 

DropBoofe 



As the system grows, specific modules will move from active development to 
maintenance mode. Make sure that these modules are constructed in such a 
ongoing development doesn't cause errors to occur in previously 
ode. Such errors are called regression errors. 



Be Mindful of Security 

The media is filled with reports of people exploiting security faults in soft- 
ware. As you design and implement your application, you must be mindful of 
security. Security faults can creep into your system in many ways: 

v 0 Taking advantage of unvalidated parameters 
u* URL tampering 

V Buffer overruns 

V Injecting commands into parameters that may make their way to SQL 

v* Exploiting known security flaws in the operating system or server 
software 

To cover all of these is beyond the scope of this chapter. However, one 
common security issue for web applications is tampering with the URL. 
Consider a program that allows users to view information about their bank 
accounts. As soon as users log on, they're shown a list of all their accounts. 
They can then click one account and get detailed information about it. The 
program was implemented to redirect the user to a page named display- 
account. jsp?number=201, which displays account 201. But what if the user 
doesn't own account 201? You may think that you're safe because the system 
provides hyperlinks only to accounts that the user owns. However, the user 
could just edit the URL line to display, for example, account number 202. If 
the web application doesn't check ownership on the account, someone else's 
account information would now be available to the unauthorized user. This 
same type of exploit can be used against hidden form variables. 

Tools can scan for various security deficiencies in a web server. For example, 
an open source scanner called Web Scarab can automate such checking. You 
can get this tool from the Open Web Application Security Project at 
http://www.owasp.org. 

Many security flaws are the result of not having the latest patches for your 
operating system or server software. Make sure that you have the most cur- 
rent patches. 
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loper, you should always test your modules as well as you can 
before they're integrated with the other modules. This is called unit testing. 
When you first create a module, you should do all unit testing by hand. 

When you're satisfied with the results of the unit test, you're ready to integrate 
your module with those developed by others. This process is called integration 
testing. Integration testing involves teamwork with other developers as your 
components are put together for the first time. 

In addition to testing performed by the developers, there will be testing per- 
formed by QA people and end users. As these users test your software, they'll 
find bugs. If you have a number of QA people and developers, a bug-tracking 
tool can be handy. In addition, bug-tracking tools allow notes to be attached to 
individual bugs. When developers or users find a bug, they can document the 
resolution. This is important because not all bugs are a result of programming 
errors. 

When the system is almost ready to be run from the production server, you 
should perform end user acceptance testing. This gives end users one final 
chance to test the system before it is rolled into production. 



Manage \lour Build Process 

The build process is one of the most important aspects of software develop- 
ment. The build process is what creates compiled files that will be run by 
WebLogic Server. The most common build method is to use operating system 
scripts to execute the commands necessary to build your application. 

Most new Java projects, including WebLogic, use Apache Ant, a tool that 
allows you to create XML script files that control how your application is 
built. Ant provides many features, including the following: 

Compiles Java files 
Creates and removes directories 
f" Copies files 

Converts text files between UNIX and Windows formats 
Archives files into JARs 

Another big advantage to ANT is that WebLogic uses it for many command-line 
utilities, such as those that create the files necessary for web services. Because 
of this, it's a great advantage to be able to call these WebLogic utilities from 
your own ANT build script. 
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Document procedures 
Define a service level agreement 
Set up on-call procedures 
Plan for growth 
Monitor your servers 
Back up your servers 
Keep your systems secure 
Understand log files 
Test with multiple machines 
Keep WebLogic up-to-date 
•••••••••••••••••••••••••••••••••••••••••••••••• 

J\ WebLogic administrator's job has many facets. And as you administer 
W \ systems, you gain experience of what works and what doesn't work. In 
this chapter, I provide some tips for WebLogic administration that I've found 
useful. 

document Procedures 

As a WebLogic administrator, you'll follow many procedures, including tasks 
such as 

f* Restarting the server 

v 0 Shutting down the server for routine maintenance 

Deploying new versions of WebLogic 
t<" Backing up the server 

Installing the latest patches 

Creating WebLogic resources such as data sources 
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You should have written instructions for each of these procedures. This 
enables you to follow the same procedure each time, ensuring consistency. 



rocedures also enable your company to perform these operations 
when you're away. In addition, if you take a new position in the company or 
with a new firm, having written procedures enables you to fulfill your respon- 
sibility to transfer knowledge to the new administrator. 



Define a Service Letfel Agreement 

A service level agreement (SLA) helps to define what end users expect from 
your server in terms of reliability. Most users expect that a system will be 
up and running 24 hours a day, 7 days a week. Such a schedule is simply not 
possible. Many events will cause your system to be down for a period of time. 
For example: 

Dealing with hardware failures 
*** Routine updates 

IV Installing new versions of WebLogic or patches to the existing version 
i>* Monitoring for acceptable performance 
Rebooting your server 

The service level agreement is the contract between you and the users that 
your system supports. This contract should specify the amount of time that 
your system will be allowed to be down through the year. 

In addition to defining maintenance periods, a properly written service level 
agreement should also specify the following: 

When maintenance will be performed 
v 0 How many minutes of unexpected outage are allowed per year 
V How soon the system must return after an unexpected outage 

How often backups will be performed 
is* The overall percent of time that the server should be up 



Set Up On*Call Procedures 

At some point, the system will go down unexpectedly. When an unexpected 
outage occurs, you and your staff must be ready to deal with it. The outage 
might be something that the administrator can handle or something related 
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to the software. If the outage is caused by a software error, a developer will 
need to get involved in the solution. Additionally, these outages may occur 

egular business hours. This is especially true if you work for a multi- 
orporation. 



Plan for Growth 

When your system is first deployed, you may not be thinking about growth. 
But you should have a plan when your current system is outgrown. In general, 
you have two choices when your system can no longer handle the amount of 
processing required: 

IV Upgrade your server to a faster machine. 
V Add additional servers to your cluster. 

Perhaps one of the simplest ways to handle more requests is to upgrade to a 
faster machine. This may mean the purchase of a new server or simply adding 
another processor to your current server. When you upgrade to a faster 
machine, you must make sure that your server is properly copied across the 
network to the new machine. All configuration settings and installed packages 
should be copied to the new machine. 

If you're running a cluster of servers, you can simply add another server. If 
you're not running a cluster of servers and your request volume is becoming 
too high, you should consider using a cluster of servers. Adding another server 
to the cluster causes WebLogic to have another server that can share some of 
the workload. This allows the application as a whole to be able to accept more 
connections. 



Monitor \/our Servers 

Monitoring your sever is an important task that every WebLogic administra- 
tor must deal with. You'll monitor whether your server is up as well as the 
server load. 

Monitoring server availability makes sure that your server is up and properly 
responding. You can choose from many software packages for monitoring 
servers. When the software detects that your server is no longer accessible, 
an e-mail message is sent to the administrator. 

WebLogic gives you many tools to monitor the load placed on a server. These 
tools are accessible from Administrative Console. For more information on 
using the monitoring tools in Administrative Console, refer to Chapter 4. 
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p data is an important part of any administrator's job. In this section, 
I describe backing up WebLogic. You will need to back up the part of your web 
application that changes. This is the SQL database. If this data is already being 
backed up by a database administrator, you don't need to worry about backing 
up application data. 

If you lose the hard drive on your WebLogic server, you'll be expected to 
reinstall everything and get the server running again. If your application 
was packaged as a WAR file, you can quickly get your application back up by 
redeploying the WAR file. 



Keep \lour Systems Secure 

Security has become an increasingly important topic. As an administrator, 
you must keep your system secure. This is accomplished through passwords, 
firewalls, and other measures. 

When you create your server, you are allowed to create an administrative 
user. You should ensure that you enter a hard-to-guess password for your 
user. Never set the password to the same value as the user ID. The adminis- 
trative user's password allows you to access Administrative Console, from 
which a person can perform any administrative task. Because of this, keep 
your password secure. 

Passwords should never be words contained in the dictionary. If your pass- 
word does exist in the dictionary, your account is vulnerable to a number of 
cracking systems. A good method for choosing passwords is to use a diction- 
ary word with a few digits on the end. 

You should make sure that your database server and application server are 
behind a firewall. You then expose port 80 of your web server to the outside 
world. Hackers will be able to access the database only through the vulnera- 
bilities of the application on the web server — they won't be able to connect 
directly to the database. 




Understand Loq Files 

When something does go wrong, the log files should be one of the first places 
that you check. Log files should contain the full stack trace for any exceptions 
thrown, so you can quickly determine which module caused the exception. 
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When you do find an error in a log file, you can often find a solution at 
groups . googl e . com. Simply paste the error message in the input box. 



ontain a large amount of information, such as 

Exceptions that were thrown 
I Beans that failed to deploy 
I v* Other resources that failed to deploy 

These errors can be tracked down by a developer. Copy the log information 
that contains the exception and send it to the developer. Make sure that you 
include the stack trace, which can help the developer. A stack trace looks like 
this: 



at weblog ic.jdbc. common. internal .JdbcInfo.validateConnectionPool 
(JdbcInfo.java:127) 

at weblog ic.jdbc. common. internal . Jdbc Info. startDataSourcet Jdbc Info. java: 260) 
at webl ogi c . jdbc . common .internal . JDBCServi ce .addDepl oyment 
(JDBCService.java:293) 

at webl ogi c. jdbc. common. internal . JDBCServi ce. addDepl oyment 
(JDBCService.java:270) 

at webl og ic. ma nagement.mbeans.custom.DeploymentTarget. addDepl oyment 
(Depl oymentTarget. java : 375 ) 

at webl ogi c .management .mbeans . custom. Depl oymentTarget. addDepl oyment 
(Depl oymentTarget .java : 154) 



Test u/ith Clusters 

If your system was developed on a single machine, it may not function 
with a cluster. Clustering has issues that don't exist with a single machine 
applications. Clustering is discussed in Chapter 16. 

If you think you'll be using a cluster to improve access, you should be devel- 
oping with two machines. Clusters provide many benefits, such as 

Performance. You'll have more than one server that can handle a 
request. 

Reliability. If one server fails, other servers can pick up for that server. 

If you'd like to ensure that your system stays compatible with clustering, test 
using at least two computers. 
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Id be aware of any patches as well as the current version of WebLogic. 
Patches correct errors and security issues that occur between major releases 
of WebLogic. You should download and install patches for WebLogic as well as 
other system components. This is particularly true of the Windows operating 
system, which has many security patches available. 

When the security of a system is compromised, it's often because the admin- 
istrator didn't have the most up-to-date patch installed. 

Upgrading to the current version of WebLogic is much less critical than apply- 
ing operating system and WebLogic patches. Sometimes it takes a redesign of 
the source code to get the current version to work properly. After the initial 
release of a new version, many companies prefer to wait until the release has 
been proven. When you decide to upgrade to the latest version of WebLogic, 
you should do so on a test server. Then, after you verify that the test server is 
performing well, you can put the new version onto your production system. 
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Test your system 

Conduct a stress test 

Set up a parallel environment 

Perform fault testing 

Set up a bug tracking system 

Formulate a disaster recovery plan 

Pick your date 

Keep the lines of communication open 
Be ready for anything 
Be ready with support 



• • • • • 



Sooner or later, you'll determine that your system is ready to enter 
production. The process by which you take your system into production 
is referred to as going live. This process can be stressful to users, administra- 
tors, and programmers alike. To help minimize that stress, follow the ten tips 
in this chapter before you go live. 



Test \lour System 

It may sound obvious, but you should test your system before it rolls into 
production. By testing, I don't mean that the developers haven't seen the 
system crash in awhile. I mean real solid testing that mimics how your appli- 
cation will be used. 

Because you can't test for everything, you must provide a way for problems 
to be resolved. Ask yourself the following: 
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Have you provided a support e-mail for users to report bugs? 
Are errors and exceptions logged and dealt with? 



t do you do with reported bugs? Are they tracked? 

i>* Are you monitoring your system? How quickly would you know about 
a problem? 

Ask your QA people to produce a test script for your system. A test-scripting 
program also allows you to retest the entire system quickly. This can be 
useful when a programmer submits a change and you need to analyze the 
change's effect on the system. 



Conduct a Stress Test 

A system that's going live will face many stresses that a development system 
never encountered. For example, when your system was being developed, 
WebLogic Server probably handled requests from only the developers. When 
the system goes live, large numbers of users may access the system. These 
additional users will place stress on WebLogic Server. 

Every system has a breaking point, where it can handle no more users. If your 
site's initial users push the server beyond its limits, it will go down. The first 
step in conducting a stress test is to try to estimate how many users your 
system will likely have at a time. If the system is a replacement, you can use 
statistics from the previous system. If this is a new system, you'll have to esti- 
mate as best you can. 

After you estimate the amount of traffic that your site will likely see, test 
that your site is up to the challenge. Testing tools simulate the load of many 
simultaneous users and tell you the breaking point of your server. Here are a 
few examples: 

WebStone at www . mi ndcraf t . com/webstone/ 
I Paessler at www . paessl er .com/ 

Web Performance at www . webperf ormancei nc . com/ 

Don't conduct a stress test just to prove that your current system can handle 
the expected amount of traffic. Stress tests should determine the breaking 
point of your server. After you know this breaking point, you can plan accord- 
ingly as you approach that point. 
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users a way back as you roll out the new production system. The 
most common way of doing this is a parallel system deployment. That is, you 
keep the old system up for some specific amount of time, while the users 
adjust to the new system — and while bugs are fixed. A parallel rollout gives 
you the following benefits: 

Minimizes interruption to business processes 
W Allows you time to fix initial bugs in the new system 
V Uses the old system to verify the results of the new system 

You should specify the amount of time that you will leave the old system up. 
If that amount of time is too long, users might delay adopting the new system. 



Perform Fault Testing 




Most likely, your new server has been designed to withstand some degree of 
hardware failure. Such systems include the following: 

V A battery backup power supply in the event of a power failure 
A generator in the event of an extended power failure 

f Redundant web, application, and database servers 

Co-location in the event of failure of the entire main facility 

V Redundant Internet connections 



You should have documented procedures that test the performance of each 
system. Whichever of these systems you have in place, make sure that 
they're functioning. You don't want to test such systems when the first hard- 
ware or power outage occurs. 

Excessive testing on some uninterruptible power supply (UPS) systems can 
greatly shorten the battery life — and replacement batteries can be expensive. 
Check with your vendor to determine the recommended frequency of testing. 



Set Up a Buy Tracking System 

No system is perfect. Your system will have bugs, and you should have a pro- 
cedure for tracking them. Many bug-tracking systems are available, such as 
the following: 



Part VI: The Part of Tens 



dBook© 



V Bug Collector Pro at www . nesbi tt . com 
FogBugz at www. fogcreek. com/ FogBUGZ/ 

vark at www .red- gate . com/bug_tracki ng . htm 



These systems often manage the entire life of a bug, as follows: 

1. The bug is reported. 

2. The bug is assigned to a developer. 

3. The developer corrects the bug. 

4. The bug is QA tested. 

5. The bug issue is closed. 

Another important consideration when tracking bugs is to separate issues 
into two categories: true bugs and suggestions for improvement. A bug 
occurs when the program does not perform as it was designed. A suggestion 
for improvement, also known as a feature request, is something beyond the 
original scope of the program. 

Programmers find it daunting when they have to treat everything as a bug, 
which implies that they did something wrong. Additional features, although 
perhaps just as pressing as bugs, should be recognized as a shortcoming in 
the requirement-gathering phase. 

Some bug-collection packages offer Web access, which allows your users to 
report bugs from a simple browser. This can be a big help because most bug- 
collection packages require users to be on the same network. 



Formulate a Disaster Recovery Plan 

Any number of issues can affect your main data center, such as a backed-up 
sewer that floods your computer room or a nearby transformer that explodes 
and leaves you without power for nearly a day. Disaster recovery means that 
your application could continue, even after a total loss of your main facility. 
You should assume that all computer systems and data from that site are 
gone. You should also assume that you won't be able to reach employees 
from the main site for some time. 

The most common solution to disaster recovery is co-location, whereby you 
set up a separate data center. Often, a vendor company will lease computer 
equipment to get your system up and running from a remote location. 
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Choose l/our Date 



You should choose a go-live date well in advance. Those who will be using 
the system should know this date, so that they can plan accordingly. Try not 
to schedule the go-live date at a busy time of the year. Coordinate the go-live 
date so that it occurs on the first day of a quarter or the first day of the 
month, depending on how your company does its accounting. 



Keep the Lines of Communication Open 

After your system goes live, keep in contact with the users of your system. 
Being able to quickly contact someone who is knowledgeable about the new 
program will make users feel much better about the new system. And being 
in contact with users will give you valuable feedback about the program and 
what can be improved. 

Be Ready (or Anything 

Be ready for long hours during the first few weeks when you go live. Never 
forget Murphy's law: Whatever can go wrong, will go wrong — and at the 
worst possible time. Although you can't anticipate every problem that can 
occur after you go live, you should have procedures in place for dealing with 
most problems. 



Be Ready u/ith Support 

You will never be totally ready to go live. There is always more testing or 
more preparation to do. Eventually, however, the go-live date will arrive and 
users will begin using your system. Now is the time to provide support to the 
users. Collect and correct bugs. Explain features of the system that users 
don't understand — many times, users mistake unknown functions as bugs. 
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web services packaging with, 162, 167 
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file, 147 
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web application setup, 70-77 

web servers versus, 69-70 
application-client.xml file, 144 
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application.xml file, 146-148 
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asynchronous web services 
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for, 161 
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Bug Collector Pro, 336 
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build.xml file 
client stub generation, 175-177 
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cl asspath method, 123 
CLASS PATH variable 

backend components, 164 
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load balancing configuration, 285 
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Configure a new Global Role link 

(Administration Console), 314, 315 
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Configure a new User link (Administration 

Console), 309, 310 
Congratulations message, GUI installation, 

23,24 

Connection class (Java Messaging 

Service), 253-255 
connection factories 

basic functions, 240, 254 

creating, 241-243 
Connection Factories folder, 241, 242 
connection pools 

assigning to clustered servers, 288 

basic functions, 203-204 
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abstract bean implementation, 128-131 
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data source definition, 206-208 
defined, 105, 111 
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value object construction, 123-125 
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Designer pull-down menu, 223 
destEar attribute, servi cegen node, 163 
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documents-oriented operations, 165 
Domain Configuration Wizard 

configuring new Windows service, 41 

to create web servers, 71 

creating clustered domains, 276-283 



Index 



Domain Log Filters configuration area, 



49, 50 



Configuration Wizan 



(DNS), 221,302 



Configuration Wizard property, 31 
domains versus, 48 
unauthorized tampering with, 302, 325 
domai n . di rectory property 
(Configuration Wizard), 32 
domains 
clustered, 274, 276-283 
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EAR files 
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resources, 308 
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load balancing requests, 285 
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groups 

assigning new users to, 311, 313 
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clustering requirements, 276 

console instructions, 26-29 

GUI instructions, 21-24 

overview, 17-21 

silent mode instructions, 29-34 
installer properties files. See templates 
installNodeMgrSvc.cmd,61 
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Java class backend components, 158-159 
Java code 
for backend components, 158-159 
documentation, 321-322 
in JavaServer Pages, 81, 83 
for web service operations, 187 
Java compilers, editing for performance, 
299-300 

Java Database Connectivity (JDBC) 
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ADMIN property (Configuration 

Wizard), 32 
managedServerRegName property 

(Configuration Wizard), 32 
managedServerSSLListenPort property 

(Configuration Wizard), 32 
mandatory properties (silent 

installation), 30 
manual descriptor creation, 146-148 
mapping files, 136-137 
max-beans-i n-cache element, weblogic- 
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operating system build scripts, 326 

operating system patches, 325 
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paging stores, 246, 250 

parallel system deployment, 335 

passwords 

Administration Console login, 47-48 

Configuration Wizard property, 31 

encryption, 302 

entering for new users, 31 1 
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point-to-point messaging 
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protocol attribute (servi ce node), 165 
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proxies, for dynamic web services, 181 
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clustering for, 16, 47, 230, 273 
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Remember icon, 5 

remote element, 92, 119 
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web applications, 74, 79 
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scripts 
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build.xml file for client stub generation, 
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Service), 254 
ServerSessi on Pool 1 class (Java 

Messaging Service), 254 
ServerSessi onPool Factory class (Java 

Messaging Service), 254 
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servi ceName attribute (service 
node), 165 
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configuring WebLogic as, 40-43, 73 

starting Node Manager as, 61 
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Servi etRequest parameter, 83 
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servlets, 79, 82-83 
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setenv . cmd command, 150 
setEn v . cmd command, 167 
setenv . sh command, 150 
setEnv . sh command, 167 
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web applications, 70-77 
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shipping applications, transactions for, 232 
shopping cart programs, 233 
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instructions, 29-34 
overview, 17 

package installer required, 20 
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WebLogic Server support, 15 
SLAs (service level agreements), 328 
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file, 147 
SOAP envelope, 156 
software costs, 272 
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SQL code. See structured query 
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SQL For Dummies (Taylor, Allen G.), 107 
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Server), 278 
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Server), 278, 280 
SSL protocol. See Secure Socket Layer 

(SSL) protocol 
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SSL/HTTPS, WebLogic Server support, 16 
stack traces, 331 
staging directories 
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for web services, 167 
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Start menu 
opening command prompt, 28 
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from, 277 

starting WebLogic Server from, 39, 73 

starting WebLogic Workshop from, 184 
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startNodeManager.cmd script, 61 
startNodeManager.sh script, 61 
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startup scripts. See also WebLogic Server 
startup 

Administration Server, 56 

daemons (UNIX), 44 

Node Manager, 60-61 
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WebLogic Server options, 34-39 
startWebLogic.cmd script, 36-37 
startWLS.cmd file, 37 
startWLS.cmd script, 299 
startWLS.sh script, 299 
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creating, 99-104 
stateless session beans 

for backend components, 159-161 

compiling, 94-97 
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deploying, 97-98 
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debugger), 194 
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debugger), 194 
Step Over action (WebLogic Workshop 
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Stop action (WebLogic Workshop 

debugger), 194 
Stores folder (Administration Console), 
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String return type, 187 
strings, 180 

D r o pfraMS^ (SQL) 

executing statements in JDBC, 214- 
table creation code, 108 
transaction statements, 235-236 
stuck threads, detecting, 295 
sty 1 e attribute (servi ce node), 165 
su command (UNIX), 43 
subscriber program, 263-265 
suggestions for improvement, 

bugs versus, 336 
superuser, 43 
support for users, 337 
swi tch statements, breakpoints with, 193 
symbolic links to startup scripts, 44 
synchronous web services 
asynchronous versus, 157 
building, 158-161 
packaging, 162-167 
synchronous write policies, 244 
system requirements (WebLogic Server), 
18-19 
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tag libraries, 142, 143 

tag library descriptor (TLD) files, 142 

targetNamespace attribute (servi ce 

node), 165 
Tasks configuration area, 49, 50 
Taylor, Allen G. (SQL For Dummies), 107 
TCP/IP ports, specifying, 51, 63 
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templates 

creating for silent mode installation, 30-33 

EJB remote interface, 88 

messaging services, 241, 248-249 

server domains, 25 
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thin client applications, 292 
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Tip icon, 5 
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testing, 334 
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creating, 241, 252-253 
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applying, 233-237 
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trusted CA certificates, 302 

loading into keystore, 306 

obtaining, 303-304 
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tampering with, 302, 325 
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systems, 335 
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UNIX 
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Node Manager startup script, 61 
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standard startup script, 299 
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systems, 335 
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WAR files. See web archive (WAR) files 
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